Agent Team

English | 中文

A Claude Code plugin: Claude orchestrates, Executor implements, codex reviews.

Claude acts as the sole brain — splitting your request into tasks, writing each task's spec, and running an Executor/Reviewer loop per task in an isolated git worktree. The Executor (grok by default, or codex if grok is not installed / you pass --executor codex) implements a task; codex (Reviewer, read-only sandbox) reviews the diff; Claude judges the result, reworks if needed, commits, merges, and reports. Review is never bypassed — not even for code Claude writes itself.

Requirements

• Claude Code
• codex CLI, logged in (Reviewer; also usable as Executor)
• grok CLI, logged in — optional if you use --executor codex or auto-fallback
• A git repository as your working directory (this is a git-worktree-based workflow — it will not run outside one)
• Node.js (the orchestration scripts are plain .mjs, no dependencies)

Windows, macOS, and Linux are all supported. The scripts resolve grok/codex binaries without going through a shell (see docs/CONTEXT.md for why).

Executor selection

Mode	Behavior
auto (default)	Use grok if available, else codex
grok	Require grok
codex	Require codex as Executor (Reviewer stays codex → independence: weak)

/agent-team --executor auto <request>
/agent-team --executor codex <request>   # no grok needed

Env overrides: AGENTTEAM_EXECUTOR, AGENTTEAM_GROK_BIN, AGENTTEAM_CODEX_BIN. When auto falls back to codex, the plan approval step states that both write and review are codex (independence: weak). See ADR-0003.

Install

/plugin marketplace add Tenon-Net/Agent-Team
/plugin install agent-team

Current plugin version: 1.1.1 (see CHANGELOG.md).

Update

Claude Code detects upgrades from the version field in .claude-plugin/plugin.json (not from Git tags). After we publish a new version to this repo:

/plugin marketplace update agent-team
/plugin update agent-team

Optional: in /plugin → Marketplaces → this marketplace → enable auto-update. Third-party marketplaces default to auto-update off.

If a skill still looks stale, run /reload-plugins (or restart Claude Code).

Usage

In any git repo, inside a Claude Code session:

/agent-team add input validation to the signup form

Claude will:

1. Split the request into small, independently-reviewable tasks and write a plan.md — and stop there for your approval before touching anything.
2. For each task: create a worktree, have grok implement it against a spec Claude wrote, have codex review the diff read-only, and merge on a clean pass.
3. If a round gets a blocker, rework it automatically up to a hard cap (see "Rework loop" below), escalating to you if it's still blocked after that.
4. Merge everything into a summary branch and report task/status/author/ round/blocker-count/branch, plus next actions (including the merge command for the summary branch, and worktree paths for anything left needs-human).

Other invocations:

/agent-team --dry-run <request>              # plan + preflight only, no worktrees
/agent-team --resume <run-id>                 # continue an interrupted run
/agent-team --executor codex <request>        # Executor = codex (no grok)

How the rework loop works

With grok as Executor:

r1 (grok, fresh session) → blocker? → r2 (grok, --resume r1's session)
                                     → blocker? → r3 (grok, fresh session,
                                                        spec rewritten by Claude)
                                                 → blocker? → r4 (Claude writes it)
                                                             → blocker? → needs-human

With codex as Executor, r2/r3 are always fresh (no session resume); reviewer findings are embedded in the next prompt instead.

There is no round 5. needs-human preserves the worktree (it's the scene, not garbage) and shows up in the final report for you to resolve by hand.

Claude only writes code directly in two cases: a single-file, no-behavior- change trivial edit, or the round-4 fallback above — and both still go through the same reviewer pass as everything else.

Why not just use omc team / codex review?

Two design decisions are recorded as ADRs in skills/agent-team/docs/adr/:

• ADR-0001 — this is a single-brain-controlled pipeline (Claude reads structured results and decides the next step), not a multi-worker autonomy model. omc team is also unable to pass --json-schema/--output-schema through, which the whole trust/gate design depends on.
• ADR-0002 — codex review has no --output-schema, -o, or -C, so the Reviewer is implemented with codex exec instead, pointed at the worktree read-only.

Design notes and hard-won facts

Every command shape in this plugin was arrived at by running it against the real CLIs, not by reading --help text alone — skills/agent-team/docs/CONTEXT.md has the full list, with exact reproductions: why --json-schema breaks the Executor, why exit code 0 doesn't mean success, why every path must be absolute, the git branch-naming trap (agent/<run-id> can't coexist with agent/<run-id>/<task>), and more.

Testing the orchestration logic without spending API cost

bash scripts/tests/regress.sh

Runs run-executor.mjs/run-reviewer.mjs/resolve-executor.mjs against deterministic stub CLIs (scripts/tests/stub-grok.mjs, stub-codex.mjs) covering grok and codex Executor paths, auto-fallback, and Reviewer failure modes real models rarely produce on their own (dishonest self-report, contradictory verdict-vs-findings, capacity errors). Free, offline, and self-contained — it builds its own throwaway sandbox under a temp directory.

License

MIT