secondmate

Your agent writes the code. A different model tries to break it.
Only what survives ships, and only when you say go. 🐾

secondmate is a Claude Code plugin that makes your AI coding agent check its own work with a second opinion.

When an agent writes code, the same agent usually reviews it, so it misses its own mistakes. secondmate
splits the job in two: one agent writes the change (the maker), a different AI model reviews it
(the checker), and nothing gets merged until the checker passes it, the change clears an automated safety
gate, and you give the final OK.

Because the checker is a different model than the maker, it catches bugs the maker is blind to. secondmate
also keeps long runs from going off the rails, remembers your decisions across restarts, and can hand hard
analysis to a reasoning model on the side. Works with any coding-agent CLI.

⚡ Quick start

claude plugin marketplace add eshwarvijay/secondmate
claude plugin install secondmate@secondmate
# restart Claude Code, then let it set itself up — you just approve each step:
/secondmate-doctor

Then run any change through the loop:

/loop-task add a rate limiter to the API and prove it works

secondmate spawns the maker in an isolated worktree, runs a different model as an edit-locked checker,
gates on its {verdict} plus a clean verify-gate, and asks you before anything merges. Need a quick
read-only analysis? /secondmate-reason why does this test flake only in CI?

🔁 How it works

flowchart LR
    A[loop-task: goal] --> P[plan-committee<br/>6 models in parallel]
    P --> S[supervisor: Sonnet<br/>synthesizes plan]
    S --> M[maker<br/>Claude or pi+Qwen --thinking medium]
    M --> C[checker<br/>gpt-terra, read-only]
    C --> V{verdict}
    V -- fail --> S2[supervisor<br/>synthesizes fix plan]
    S2 --> M
    V -- pass --> G{verify-gate}
    G -- refuse --> M
    G -- pass --> H{{your approval}}
    H -- merge --> D[ship]

The planning committee runs unconditionally for every task. For complex tasks it runs 6 open-weight models (DeepSeek-R1, Qwen3-Next-80B, Qwen3-Coder-Next, Kimi K3 (bedrock cross-region inference profile: global.moonshotai.kimi-k3), Mistral-Large-3, GLM-5) in parallel, each covering a different dimension. Sonnet synthesizes all outputs into one consolidated plan, then routes to the right maker: Claude for tasks needing judgment or MCP tools, pi + Qwen3-Coder (--thinking medium) for well-specified pure-code tasks.

On a checker fail, the supervisor synthesizes a fix plan and hands it back to the same maker (task-scoped agent name, same worktree) — never fixes inline. The supervisor never writes project code.

Deeper dive: docs/ARCHITECTURE.md — roles, the guarantee behind every stage, and the full component map.

💡 Best with herdr. Inside herdr the full loop runs natively: herdr worktree create spawns the maker worktree + workspace in one call; the pi maker runs as a lifecycle-tracked herdr agent (blocked recovery, stall detection); the checker runs via herdr pane run + pane wait-output — no timeout caps, no silent failures. Anywhere else secondmate falls back to headless sub-agents with the same guards.

🧰 What's inside

Commands: /secondmate-doctor · /secondmate-reason · /secondmate-verify · /loop-task

⚠️ Scope guard for pi makers requires an explicit --extension flag at launch time — there is no auto-discovery.

Both implementations share the same permanent limitations: they recognize literal patterns only, not a shell parser,
not data-flow analysis, not an OS sandbox. They will not be extended further to chase new bypasses — every round
of "found one, patched it" converges on the same wall. They do not reliably catch: (a) alternate redirection syntax
with no space before the operator (e.g. cat</etc/passwd, >/etc/foo); (b) indirect/deferred execution where the
program invoked arrives as data at runtime rather than a literal token (e.g. find . -exec cat /etc/passwd \;,
... | xargs -0 sh -c 'cat "$0"'); (c) interpreter code that shells out via a library call instead of visible path
text (e.g. python3 -c "import os; os.system('cat /etc/passwd')", Node's child_process, Ruby/Perl backticks).
These are representative examples of permanent gaps, not a todo list — closing them for real needs OS-level
sandboxing (chroot/seccomp/containers), which is explicitly out of scope here.

🔎 Specialized review lenses

The checker isn't one generic reviewer. Per task, secondmate loads only the specialized disciplines the
diff actually needs — a router → sub-skill design (progressive disclosure), so the checker gets focused
context instead of a generic dump. Lenses live in bin/lenses/<role>/; the supervisor reads each role's
ROUTER.md, matches the diff, and injects just the matching sub-lenses
(--lens redteam/injection --lens qa/coverage).

Add your own: drop bin/lenses/<role>/<name>.md (a lean, specialized discipline) and list it in that role's ROUTER.md.

📦 Requirements

git, gh, python3, and (recommended) a checker harness CLI (defaults to pi).
Just run /secondmate-doctor: it detects and installs everything, asking only for your approval, and never
hands you a manual checklist.

No harness? You still get a cross-model check. secondmate falls back to a second Claude model as the
checker, in-session, so the maker is still not the checker. An external harness like pi gives a stronger
cross-vendor check (a different vendor, not just a different Claude model). Either way, the models need
credentials only you can supply.

The default model IDs are Amazon Bedrock inference-profile IDs — override them for your provider.

# install from a local clone instead of GitHub
claude plugin marketplace add /path/to/secondmate
claude plugin install secondmate@secondmate

# verify everything
bin/verdict.py selfcheck && bin/loop-guard.sh selfcheck && bin/verify-gate.sh --selfcheck \
  && bin/prune-output.sh --selfcheck && bin/run-round.sh selfcheck && bin/reason.sh --selfcheck \
  && bin/plan-committee.sh --selfcheck && bin/doctor.sh --selfcheck && bin/scope-guard.py selfcheck \
  && bin/mark-maker.sh --selfcheck && bin/new-worktree.sh --selfcheck && bin/sync-worktree-skills.sh --selfcheck \
  && bin/herdr-pane.sh --selfcheck \
  && bin/log-round.sh --selfcheck && bin/caffeinate-guard.sh --selfcheck && bin/checker-progress.py selfcheck \
  && bin/hold.py selfcheck && bin/committee-output.py --selfcheck \
  && bin/claim-ledger.py selfcheck && bin/merge-sequencer.sh --selfcheck \
  && bin/dispatch-report.py selfcheck \
  && echo ALL_OK
claude plugin validate .

License

MIT © Eshwar Vijay