ralpha-team

ralpha-team

A Claude Code plugin that runs your prompt in a loop until the work is genuinely done — verified by a shell command, not just Claude saying so.

The core idea: instead of one long session where the model tries to hold everything in context, you run many short sessions. Each one reads the current state from disk, does one unit of work, commits, and exits. The loop re-invokes it. Fresh context every time. State lives in files and git history, not in the model's memory.

This approach comes from Geoffrey Huntley's Ralph technique, ported here to Claude Code's native plugin system.

Why this works

Long coding sessions degrade. The model starts strong, then slowly loses track of earlier constraints as the context fills up. It might re-implement something it already built, or forget that a test was passing and break it. By iteration 15 in a single session, you're often fighting accumulated drift as much as the actual problem.

What drift looks like in practice: Claude implements an auth module in message 10, then in message 40, facing a related bug, re-reads the file and doesn't recognize it as something it already wrote. Or it accepts a constraint early ("don't use global state") then violates it later because that constraint has been pushed far enough back in context that it's no longer in the effective attention window. Context windows are large but not free — as they fill with tool outputs, intermediate reasoning, and error messages, early instructions lose ground.

Short loops with fresh context don't have this property. Every iteration, Claude re-reads the objective, sees what's in git, and works from that ground truth rather than from its fading recollection of the last 50 messages. You re-read specs on every iteration, which costs something in tokens, but the consistency is worth it for anything non-trivial.

The dual gate is the other piece. Without some form of backpressure, Claude will claim it's done when it isn't. It's not deceptive — it's just that "the feature is now complete" is a natural way to narrate work, not necessarily a factual claim. The gate separates an intentional completion claim from incidental completion-sounding narration, then independently checks that the claim is true.

Install

Inside Claude Code, run each command separately:

/plugin marketplace add James-Traina/science-plugins

/plugin install ralpha-team@science-plugins

Both modes require jq (brew install jq on macOS, apt install jq on Linux). Team mode additionally requires the experimental flag in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Three modes

Plan

Before writing any code, run a planning loop. It scans your specs and existing codebase, compares them, and produces IMPLEMENTATION_PLAN.md — a flat checklist of tasks, each with explicit file scope and a done criterion.

Why plan separately? Without a plan, each build iteration has to re-reason the scope from scratch. The model reads the codebase, figures out what's missing, picks something to work on, and implements it. Next iteration, it reads the codebase again and might pick a different thing, or pick the same thing having forgotten progress was already made. A plan file gives fresh-context iterations something stable to draw from: pick the first unchecked task, do it, check it off.

The plan command runs in a short loop (1–3 iterations is usually enough) because the output is a file, not code. Once IMPLEMENTATION_PLAN.md exists, both solo and team modes read it automatically and use its unchecked items as the task queue.

/ralpha-team:plan "Build a payment processing service with Stripe, webhooks, and idempotency" \
  --max-iterations 3

Solo

One Claude session, looping. The default for most things. Good for bug fixes, single features, refactors, anything where the work is roughly sequential.

Each iteration sees the previous iteration's work via git log and file state. The model can't remember what it said last time, but it can see what it committed. Git history is the right kind of memory here — concrete and verifiable, not approximate and decaying.

The loop continues until both the completion promise and verification command pass on the same iteration, or until --max-iterations is reached. Between iterations, the failure output — exactly what went wrong — is injected into the next iteration's context so Claude can respond to it, without carrying that failure report in memory for the entire session.

/ralpha-team:solo "Fix the token refresh race condition in auth/session.py" \
  --completion-promise 'FIXED' \
  --verify-command 'pytest tests/test_auth.py -v' \
  --max-iterations 15

Team