Agent Teams Mcp

中文文档 →

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 ` injections — **no polling, no inboxread, 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](#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//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 

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//            │
└──────────────┬────────────────────────────────────┘
               │ 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 `` 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](#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](.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 `` 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](.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](CONTRIBUTING.md) for conventions.

Design docs worth reading:

• [.plans/agent-teams-v2/decisions.md](.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](.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](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jessepwj
• Source: jessepwj/agent-teams-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.