中文文档 →

An MCP server that turns Claude Code into a coordinator for a team of AI worker agents — with true push from workers back to the lead and a live web UI for observing the whole team.

agent-teams-mcp

A Rust MCP server that lets your Claude Code session lead a team of AI workers (Claude Code, Codex, Gemini CLI). Worker replies are pushed back to the lead automatically as <system-reminder> injections — no polling, no inbox_read, no manual checking. A live web UI on http://127.0.0.1:8787 shows the whole team chatting in real time.

Install

Prerequisites: Rust 1.85+, Node.js 14+.

git clone https://github.com/jessepwj/agent-teams-mcp
cd agent-teams-mcp
cargo install --path .
team_mode_service install-global

Then fully restart Claude Code (close every window, relaunch). Run /mcp — you should see team-mode connected. After that, cd into any project and use it. Each project gets its own isolated team data.

The one pitfall to remember: any edit to .mcp.json or .claude/settings.json needs a full CC restart. /mcp reconnect does NOT reload hooks. See Troubleshooting.

Why this exists

Claude Code exposes MCP tool calls but does not auto-react to MCP resources/updated notifications. The official Channels API needs claude.ai OAuth — many people run Claude Code with an API key.

This project uses Claude Code's documented Stop hook + asyncRewake pattern to push worker replies all the way back into the lead's session:

Worker reply
  → service appends to .agent-teams/<team>/lead_pending.jsonl
  → Stop hook fires when CC's turn ends
  → hook drains the per-team file, writes stderr, exits 2
  → CC opens a new turn with the reply as a <system-reminder>

Median end-to-end latency: ~50 ms. No polling, no token burn.

Architecture

┌───────────────────────────────────────────────────┐
│  Claude Code (your session) — the LEAD            │
│  .mcp.json  ──► HTTP MCP at 127.0.0.1:8786/mcp   │
│  .claude/   ──► Stop hook (asyncRewake)          │
└──────────────┬────────────────────────────────────┘
               │ Streamable HTTP
┌──────────────▼────────────────────────────────────┐
│  team_mode_service (durable localhost daemon)     │
│   • 8 MCP tools                                   │
│   • TeamService / MessageService / InboxService   │
│   • Worker subprocess orchestrator                │
│   • Web UI on :8787 (auto-opens)                  │
│   • Storage under .agent-teams/<team>/            │
└──────────────┬────────────────────────────────────┘
               │ spawns
   ┌───────────┼───────────┬──────────────┐
   ▼           ▼           ▼              ▼
 alice       bob        carol         lead-pending
(claude)   (codex)    (gemini)      (per-team queue)

The service stays up across Claude Code reconnects and owns all worker state. Stop it explicitly with scripts/team-mode-service.ps1 stop when you want it gone.

What's in the box

• 8 MCP tools — team_create / team_list / team_delete / worker_add / worker_list / worker_remove / send_message / inbox_read. That's the whole surface.
• Push to the lead's terminal — replies arrive as <system-reminder> automatically. No polling.
• Live web UI (127.0.0.1:8787+) — three-pane layout, per-sender colors, @mention highlighting, full Claude Code / Codex JSONL session transcripts, sticky composer for human input.
• Multi-backend workers — claude-code / codex / gemini-cli. Lead must stay Claude Code (see Codex as Lead).
• Strict routing — @mention validation, caller-attributed senders, workers can only send into their bound team. No forging.
• Per-project isolation — one durable service hosts multiple CC sessions in different projects; teams never bleed across.
• Worker liveness + revival — worker_remove is soft-delete (profile kept). worker_add on_existing=reuse fast-resumes.
• Mid-turn delivery — when the lead is busy with tools, replies surface via PostToolUse hook within ~3 s instead of waiting for turn end.
• 351 unit tests, zero warnings.

MCP tools

Tool	Required	Optional	Purpose
team_create	name	cwd	Create team; lead member auto-added. Auto-launches web UI.
team_list	—	—	List all teams with ownerStatus.
team_delete	name	—	Stop workers + remove team. Returns shutdown_failures.
worker_add	team, name	adapter, model, cwd, system_prompt, env, on_existing	Spawn worker. on_existing required if profile exists.
worker_list	team	—	List workers; dead ones marked, hint to revive.
worker_remove	team, name	—	Soft-remove; profile retained.
send_message	team, text	—	Send into the team room. sender derived from caller. @mention required.
inbox_read	team	limit, unread_only, auto_ack	Pull-mode fallback for audits. Not the canonical channel.

Full schemas in .plans/agent-teams-v2/docs/02-current-system/mcp-tools-reference.md.

Backend matrix

	claude-code	codex	gemini-cli
Persistent process	✓	✓	— (per-turn)
session_id capture	✓	✓ (thread.id)	—
Web UI session transcript	✓	✓	—
Full-access mode	✓ (bypassPermissions)	✓ (danger-full-access)	n/a
Multi-turn memory	native	native	rolling 50-turn window

Claude Code workers need CLAUDE_CODE_GIT_BASH_PATH on Windows (auto-detected from common Git paths; set manually if non-standard). On Windows MSVC, source vcvars64.bat before starting the service so workers inherit the MSVC linker — easiest way is to use scripts/team-mode-service.ps1 start.

Troubleshooting

send_message returns success but no <system-reminder> arrives. Triage in this order:

1. Did you fully restart Claude Code after install or after editing .claude/settings.json? Hooks only load at CC startup. /mcp reconnect is not enough. Quit all CC windows, relaunch.
2. Is the worker actually replying? tail -f ~/.team-mode/runtime/service.log should show appends to lead_pending. If not, the backend CLI may be missing from PATH.
3. Is the Stop hook firing? tail -f .agent-teams/.lead-pending-wake.log should show injection lines. None → hook not loaded → step 1.
4. Still stuck? See .plans/agent-teams-v2/docs/03-operations/open-source-deployment.md for the full triage table (15+ scenarios).

Codex as Lead

Not currently supported. The Stop-hook push is a Claude Code feature — Codex CLI has no equivalent blocking hook (openai/codex#8375).

Codex as a worker is fully supported with full session-transcript parity in the web UI.

Development

git clone https://github.com/jessepwj/agent-teams-mcp
cd agent-teams-mcp
bash scripts/setup.sh    # or: powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
cargo test --lib         # 351 tests, ~1s
cargo build --release --bin team_mode_service

Adding a backend? See src/backend/{claude_code,codex,gemini}.rs for reference impls. AgentLoop drives all backends uniformly. Read CONTRIBUTING.md for conventions.

Design docs worth reading:

• .plans/agent-teams-v2/decisions.md — ADRs for current HTTP service + async wake
• .plans/agent-teams-v2/docs/05-design-history/hook-push-design.md — Stop hook design rationale

Credits

Derived from and builds on github.com/ZhangHanDong/agent-teams-rs (MIT, © 2025 Zhang Han Dong), which provides the core runtime, backends, and domain. This fork adds:

• The Stop-hook + asyncRewake push architecture
• A durable localhost HTTP service that survives Claude Code reconnects
• The live web UI (per-sender colors, session transcripts, human-in-the-loop)
• Per-team data layout, unified members.json v=1, caller-attributed senders
• Strict send_message routing, worker revival, mid-turn delivery, per-project isolation

License

MIT — see LICENSE.