tools-claude-code-teams-mcp

Overview

Operate the Claude Teams MCP workflow end to end: create teams, spawn teammates, assign tasks, read inbox messages, and shut teammates down safely.

When to use

• User asks to test or demo teams/teammates
• User wants opencode backend teammates
• User needs help with teammate startup, inbox polling, or shutdown behavior
• User asks how spawn inputs work (model, prompt/persona, backend)

Sub-skills

• sub-skills/experimental-background-monitor.md: run an external orchestrator against opencode serve (events + async prompts) for continuous monitoring/control

Core workflow

• Create team with claude-teams_team_create
• Create optional test task with claude-teams_task_create
• Spawn teammate with claude-teams_spawn_teammate
• Poll lead inbox with claude-teams_poll_inbox
• Update task status with claude-teams_task_update
• Request shutdown with claude-teams_send_message (type: shutdown_request)
• Confirm teammate removal via claude-teams_read_config

Polling discipline

• Do not poll once and stop; continue polling after spawn
• Default test loop: poll until quiet for 2-3 consecutive polls
• Surface every new teammate message without waiting for user to ask
• Use claude-teams_read_inbox when you need full history context
• Before declaring success, verify no late/unread teammate messages remain

Unexpected teammate output

• Treat unexpected content (for example, policy-breaking or "rogue" messages) as a signal to intervene
• Immediately report the message to the user
• Send shutdown request and verify teammate removal from team config
• If process cleanup is partial, note tmux pane may still require manual or forced cleanup

Spawn inputs reference

Provide these fields intentionally:

• team_name: target team
• name: unique teammate name within the team
• prompt: role/persona, constraints, and exact output format
• backend_type: claude or opencode
• model: explicit model override
• subagent_type: usually general or explore
• plan_mode_required: whether plan approval is required

Backend default enforcement

• Never rely on implicit spawn defaults
• Always set backend_type explicitly on every claude-teams_spawn_teammate call
• If user wants opencode by default, also set explicit model (for example openai/gpt-5.1-codex-mini)
• In lead-session prompts, include a hard rule: "for all future spawns, use backend_type: opencode unless explicitly overridden"
• Verify backend choice after spawn via claude-teams_read_config (members[].backendType)

Opencode backend requirements

backend_type: opencode requires an opencode server URL in the MCP server process environment.

In opencode.jsonc, set MCP local server environment (not env):

{
  "mcp": {
    "claude-teams": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/cs50victor/claude-code-teams-mcp",
        "claude-teams"
      ],
      "environment": {
        "OPENCODE_SERVER_URL": "http://127.0.0.1:4098"
      },
      "enabled": true
    }
  }
}

Runtime expectations:

• Run opencode serve --port 4098
• Restart opencode after config changes
• Re-try spawn and validate by polling lead inbox

Working directory behavior

• claude-teams_spawn_teammate does not expose a direct cwd input
• To run in a subdirectory, instruct teammate to run tools with explicit workdir
• Validate by having teammate run pwd and report output

Shutdown and tmux behavior

• Shutdown can succeed at MCP level even if tmux pane remains open
• Treat team membership (claude-teams_read_config) as source of truth for active teammates
• If pane is orphaned, clean it manually with tmux (exit or tmux kill-pane -t <pane_id>)

Troubleshooting checklist

• Spawn fails with missing OPENCODE_SERVER_URL: set MCP environment, restart client session
• No inbox response: poll again, then check team config and teammate state
• Missing expected updates: continue poll loop and check unread messages via read_inbox
• Teammate appears shut down but pane remains: not a blocker; clean pane separately
• Wrong execution directory: enforce workdir in teammate instructions

Quick test playbook

• Create or reuse team
• Spawn teammate with explicit backend/model and a narrow one-shot prompt
• Poll lead inbox immediately, then continue until 2-3 consecutive empty polls
• If successful, send shutdown request and verify teammate is removed from team config
• If teammate output is unexpected, report it, then shut down and verify cleanup
• If pane lingers, treat as tmux cleanup issue, not MCP state failure