🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Claude Code Agent Teams
πŸ¦€ ClawHub

Claude Code Agent Teams

by @matthew-a-gordon

Coordinate multiple Claude Code agents to work in parallel on independent tasks like multi-lens reviews, debugging, and full-stack features with defined file...

Versionv1.0.0
Downloads2,408
Stars⭐ 2
#crypto-defi#coding#legal#communication#productivity
TERMINAL
clawhub install claude-code-teams

πŸ“– About This Skill

name: claude-code-teams description: Production skill for orchestrating Claude Code's native agent teams feature. Use when: (1) Multi-lens reviews, (2) Competing hypotheses debugging, (3) Full-stack features, (4) Architecture debates, (5) Cross-domain investigations. metadata: openclaw: emoji: "🎭" requires: bins: ["claude"] env: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"] version: "1.0.0" author: "Matthew Gordon" tags: ["agents", "teams", "claude-code", "orchestration", "coordination"]

Claude Code Agent Teams

Orchestrate multiple Claude Code agents working together on complex tasks. Agents coordinate through a shared task list, message each other directly, and work in parallel on independent scopes.

When to Use

βœ… Use for parallel independent work:

  • Multi-lens code reviews (security, performance, tests in parallel)
  • Debugging with competing hypotheses (test theories simultaneously)
  • Full-stack features (frontend/backend/tests by separate specialists)
  • Architecture decisions (adversarial debate produces stronger ADRs)
  • Cross-domain investigations (bottleneck analysis across systems)
  • Data-parallel work (inventory classification, bulk refactoring)

    • ❌ Don't use for:

  • Sequential work with tight dependencies
  • Same-file edits (conflict risk)
  • Simple tasks (coordination overhead > benefit)
  • Learning/exploration (single agent with full context is better)

    • Rule of thumb: Teams multiply token cost 3-4x. Use only when parallelization benefit exceeds coordination overhead.

    Quick Start

    1. Enable Feature

    Environment variable: 

    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

    Or settings file (~/.claude/settings.json): 

    {
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

    2. Validate Setup

    ./scripts/validate-setup.sh

    Checks for: env var set, claude CLI available, tmux installed (optional).

    3. Pick Template

    | Template | Use Case | |----------|----------| | parallel-review.md | Multi-lens code review (security + performance + tests) | | competing-hypotheses.md | Debug by testing competing theories | | fullstack-feature.md | Frontend/backend/tests coordination | | architecture-decision.md | ADR with adversarial debate | | bottleneck-analysis.md | Cross-domain performance investigation | | inventory-classification.md | Data-parallel classification/refactoring |

    Each template includes: when to use, team structure, copy-paste spawn prompt, expected outcomes.

    4. Spawn Team

    claude --pty

    Paste spawn prompt from template

    Monitor with ./scripts/team-monitor.sh (separate terminal) or Ctrl+T (in Claude Code).

    Core Principles

    1. Clear file boundaries - Each teammate owns different files/directories (prevents conflicts) 2. Use delegate mode - Lead coordinates, teammates implement (include in spawn prompt) 3. Size tasks appropriately - 5-6 self-contained tasks per teammate 4. Wait for completion - Don't let lead merge results while teammates are mid-task 5. Start with research - Spawn researchers before builders to establish shared understanding

    Cost Management

    Agent teams multiply token usage 3-4x vs single session. Each teammate has its own context window.

    Optimize with:

  • Model mixing - Opus for lead (strategic), Sonnet for teammates (tactical) = ~40% savings
  • Minimize broadcasts - Direct messages only (broadcasts copy to all teammates)
  • Right-size teams - 3 teammates usually optimal; 6+ only for highly parallel work

    • See references/cost-management.md for detailed strategies.

    Troubleshooting

    Teammates not spawning?

  • Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set
  • Restart Claude Code after setting env var

    • File conflicts?

  • Define explicit file boundaries in spawn prompt (directory-level ownership)

    • Lead implementing instead of coordinating?

  • Add "Use delegate mode: coordinate but don't implement" to spawn prompt
  • Or press Shift+Tab to cycle into delegate mode

    • See references/troubleshooting.md for full list.

    Automation

    Monitor progress: 

    ./scripts/team-monitor.sh

    Cleanup (graceful shutdown): 

    ./scripts/team-cleanup.sh

    Display Modes

    In-process (default) - All teammates in main terminal

  • Shift+Up/Down - Select teammate
  • Ctrl+T - Toggle task list
  • Escape - Interrupt teammate

    • Split-pane (requires tmux or iTerm2) - Each teammate gets own pane

  • Set teammateMode: "tmux" in ~/.claude/settings.json

    • References

  • templates/ - 6 copy-paste ready spawn prompts with usage guidance
  • scripts/ - Automation helpers (validate, monitor, cleanup)
  • references/best-practices.md - When to use teams, task sizing, file boundaries
  • references/cost-management.md - Token optimization strategies
  • references/troubleshooting.md - Common issues and solutions
  • examples/ - Real-world walkthroughs (PR review, bug hunt, feature build)

    • Comparison

    | Approach | Best For | |----------|----------| | Single session | Sequential work, exploration | | Agent teams (this skill) | Parallel independent tasks with coordination | | OpenClaw subagents | Background work, long-running tasks |

    Contributing

    Found a useful pattern? Submit PR with: 1. Template or example 2. When to use + team structure 3. Spawn prompt + expected outcomes

    Credits

    Built with insights from Claude Code documentation, ClaudeFast patterns, and OpenClaw community.

    Repository: https://github.com/matthew-a-gordon/claude-code-teams License: MIT

    ⚑ When to Use

    TriggerAction
    - Multi-lens code reviews (security, performance, tests in parallel)
    - Debugging with competing hypotheses (test theories simultaneously)
    - Full-stack features (frontend/backend/tests by separate specialists)
    - Architecture decisions (adversarial debate produces stronger ADRs)
    - Cross-domain investigations (bottleneck analysis across systems)
    - Data-parallel work (inventory classification, bulk refactoring)
    ❌ **Don't use for:**
    - Sequential work with tight dependencies
    - Same-file edits (conflict risk)
    - Simple tasks (coordination overhead > benefit)
    - Learning/exploration (single agent with full context is better)
    **Rule of thumb:** Teams multiply token cost 3-4x. Use only when parallelization benefit exceeds coordination overhead.

    πŸ’‘ Examples

    1. Enable Feature

    Environment variable: 

    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

    Or settings file (~/.claude/settings.json): 

    {
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

    2. Validate Setup

    ./scripts/validate-setup.sh

    Checks for: env var set, claude CLI available, tmux installed (optional).

    3. Pick Template

    | Template | Use Case | |----------|----------| | parallel-review.md | Multi-lens code review (security + performance + tests) | | competing-hypotheses.md | Debug by testing competing theories | | fullstack-feature.md | Frontend/backend/tests coordination | | architecture-decision.md | ADR with adversarial debate | | bottleneck-analysis.md | Cross-domain performance investigation | | inventory-classification.md | Data-parallel classification/refactoring |

    Each template includes: when to use, team structure, copy-paste spawn prompt, expected outcomes.

    4. Spawn Team

    claude --pty

    Paste spawn prompt from template

    Monitor with ./scripts/team-monitor.sh (separate terminal) or Ctrl+T (in Claude Code).

    πŸ“‹ Tips & Best Practices

    Teammates not spawning?

  • Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set
  • Restart Claude Code after setting env var

    • File conflicts?

  • Define explicit file boundaries in spawn prompt (directory-level ownership)

    • Lead implementing instead of coordinating?

  • Add "Use delegate mode: coordinate but don't implement" to spawn prompt
  • Or press Shift+Tab to cycle into delegate mode

    • See references/troubleshooting.md for full list.