Agent Teams Controls

Problem: You turned on Claude Code Agent Teams and your first team is live. But the lead keeps doing the work itself instead of delegating. Teammates edit the same files. You cannot see what anyone is actually working on. The controls to solve every one of those exist. They are just not obvious out of the box.

Quick Win: Press Shift+Tab right after starting a team to cycle into delegate mode. The lead stops touching code and focuses on coordination.

Note: This is a sibling guide to the Agent Teams overview. Start there first if you have not set up a team yet.

Display Modes

Agent Teams gives you two display modes that change how you monitor and interact with teammates.

In-Process Mode (Default)

All teammates run inside your main terminal. You move between them with keyboard shortcuts:

This works in any terminal. No extra setup, no dependencies. You watch one teammate's output at a time and switch between them on demand. For most workflows, in-process mode covers you.

Split Pane Mode

Every teammate gets its own terminal pane. You see everyone's output side by side and click into any pane to interact directly. Useful when you want to watch several teammates work through a tough problem at the same time.

Split pane mode needs tmux or iTerm2. On macOS, tmux -CC inside iTerm2 is the recommended entry point. Important: split-pane mode is NOT supported in VS Code's integrated terminal, Windows Terminal, or Ghostty. tmux has known compatibility gaps on some operating systems and runs best on macOS.

Configure your preferred mode through settings.json:

Three options:

• "auto" (default) uses split panes when you are already running inside tmux, otherwise falls back to in-process
• "tmux" enables split panes and auto-detects whether you are in tmux or iTerm2
• "in-process" forces everything into your main terminal

Override on a per-session basis with the CLI flag:

Delegate Mode

Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. That defeats the point. You told it to coordinate. It grabbed a wrench and started building.

Press Shift+Tab to cycle into delegate mode after starting a team. This restricts the lead to coordination-only tools: spawning teammates, messaging, shutting them down, and managing tasks. The lead cannot touch code directly. It stays fully on orchestration.

Use delegate mode when you want the lead acting as project manager rather than individual contributor. This matters most on larger teams, where the lead's whole job is coordination. In practice, turning delegate mode on for 4+ teammate sessions noticeably reduces wasted lead context and stops the lead from competing with its own teammates for work.

If the lead is racing ahead while teammates are still working, you can tell it directly: "Wait for your teammates to complete their tasks before proceeding." Sometimes a natural language nudge does the job. But for consistent behavior across sessions, delegate mode enforces the constraint automatically.

Plan Approval Workflow

For complex or risky tasks, require teammates to plan before they implement anything. The teammate works in read-only plan mode until the lead reviews and approves the approach.

The workflow:

1. Teammate receives the task and enters read-only mode
2. Teammate creates a plan and sends a plan approval request to the lead
3. Lead reviews the plan and either approves or rejects with feedback
4. If rejected, the teammate stays in plan mode, revises, and resubmits
5. Once approved, the teammate exits plan mode and begins implementation

The lead makes approval calls autonomously. You shape its judgment through the initial prompt. Tell it "only approve plans that include test coverage" or "reject plans that modify the database schema without a migration." The lead applies those rules as a filter on every plan it receives.

Plan mode is especially valuable when teammates are working on shared infrastructure, touching database schemas, or making changes that are expensive to unwind. The cost of planning is a fraction of the cost of rolling back a bad implementation across multiple files. For a deeper look at how plan approval plugs into a structured planning phase, see the end-to-end workflow.

Hooks for Quality Gates

Agent Teams wires into Claude Code's hook system for automated quality checks. Two hooks are built specifically for team workflows:

TeammateIdle: Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working. Use this to auto-assign follow-up tasks or redirect a teammate that finished early. If a teammate closes out its primary task while others are still grinding, a TeammateIdle hook can route review work or cleanup tasks its way without any manual step.

TaskCompleted: Runs when a task is being marked complete. Exit with code 2 to block completion and send feedback. Use this to enforce quality gates: require tests to pass, lint checks to succeed, or specific acceptance criteria to be met before a task can close.

These hooks let you build structured quality gates without watching every teammate manually. A TaskCompleted hook that runs your test suite means no task closes with broken tests, regardless of which teammate wrote the code. For a full walkthrough of the hook system and configuration, see the hooks guide.

Direct Messaging Teammates

Each teammate is a full, independent Claude Code session. You can message any teammate directly without going through the lead.

In-process mode: Use Shift+Up/Down to select a teammate, then type to send a message. Press Enter to view a teammate's full session and see everything they have done. Press Escape to interrupt their current turn if they are heading in the wrong direction.

Split-pane mode: Click into a teammate's pane to interact with their session directly. Each pane behaves exactly like a standalone Claude Code session.

This is useful when you want to redirect a specific teammate, give additional context the lead does not have, or ask a targeted follow-up question. Sometimes the fastest path is talking to the worker directly instead of routing through a coordinator.

Task Management

The shared task list coordinates every piece of work across the team. The lead creates tasks and teammates work through them. Tasks carry three states: pending, in progress, and completed. Tasks can depend on other tasks. A pending task with unresolved dependencies cannot be claimed until those dependencies complete. This mirrors the dependency chain patterns from team orchestration.

The lead can assign tasks explicitly to specific teammates, or teammates can self-claim whatever is available. After finishing a task, a teammate picks up the next unassigned, unblocked task on its own. That self-claiming behavior keeps the team moving without constant lead intervention.

Task claiming uses file locking to block race conditions where two teammates grab the same task simultaneously. The system handles task dependencies automatically: when a teammate finishes a task that others depend on, blocked tasks unblock without manual action. A teammate waiting on a dependency starts working the moment that dependency resolves.

For more on task coordination patterns, see task distribution and todo workflows.

Team Size and Model Selection

Claude picks the number of teammates based on your task complexity, or you can specify exactly what you want:

You can also mix models inside a single team. Run the lead on Opus for strategic coordination while teammates run on Sonnet for focused implementation. That balances cost with capability. The lead needs strong reasoning for task decomposition and plan approval. Teammates doing scoped implementation work often land well on Sonnet at a fraction of the cost.

For even snappier lead responses during coordination-heavy phases, combine agent teams with fast mode.

Token Cost Management

Agent Teams burns significantly more tokens than a single session. Each teammate runs its own context window, and token usage scales with active teammates. When teammates run in plan mode before implementation, expect roughly 7x the tokens of a standard session for that phase.

Where the tokens go:

• Each teammate loads project context independently (CLAUDE.md, skills, project files)
• Communication adds cost: every message between agents consumes tokens in both sender and receiver context
• Broadcasting multiplies cost by the number of teammates receiving the message
• The lead consumes tokens for coordination, task management, and result synthesis

When the cost is worth it:

• Research and review tasks where multiple perspectives catch issues a single pass would miss
• Debugging sessions where parallel hypothesis testing resolves issues faster than sequential guessing
• Large feature implementations where time savings justify the token spend
• Architectural decisions where thorough evaluation prevents costly mistakes later

When to keep costs down:

• Use Sonnet for teammates doing focused implementation work and reserve Opus for the lead
• Prefer direct messages over broadcasts when possible
• Limit team size to what the task actually requires (3 teammates is often better than 6)
• Use subagents or single sessions for routine tasks that don't need inter-agent communication
• Set clear scope for each teammate to prevent unnecessary exploration

Rough guideline: A 3-teammate team running for 30 minutes burns roughly 3-4x the tokens of a single session doing the same work sequentially. The trade is speed and coverage versus cost.

CLAUDE.md Optimization for Teams

Every teammate loads your CLAUDE.md on startup with a fresh context window. The lead's earlier discussion does not carry over, which is why CLAUDE.md quality matters so much for teams. If CLAUDE.md is vague, each teammate wastes tokens re-exploring the codebase on its own. Three teammates loading context simultaneously means 3x the token cost if that context takes exploration instead of a quick read.

Three rules make agent teams noticeably more effective:

Rule 1: Describe Your Module Boundaries

The clearer your module boundaries in CLAUDE.md, the smarter Claude splits work across teammates. Use a table:

When you tell Claude to "create a team and split by file ownership," it reads the structure and assigns explicit file lists to each teammate. Zero conflicts.

Rule 2: Keep Project Context Short and Operational

Stack, entry point, test command, database. Short reads, not explorations.

No teammate should need to ask the lead what the project is about or where files live. Every round of "what framework is this?" burns tokens in both the teammate's context and the lead's context when it answers.

Rule 3: Define What "Verified" Means

When CLAUDE.md lists how to check that things work, teammates use those signals to self-verify their own work before reporting back.

Claude adapts verification per task. For a cleanup task, teammates might use grep to verify removals. For a feature, they run the test suite. Having project-wide gates gives the lead a vocabulary for "done" it can apply automatically.

With clear rules in CLAUDE.md, teammates self-report exactly what they did without lead intervention. Clear rules in, clear reports out. For more on shaping your project files, see CLAUDE.md mastery.

Putting It Together

You now have the controls to run agent teams effectively. Start with delegate mode on your next team session and feel the difference it makes in lead behavior. Add a TaskCompleted hook to enforce your test suite. Write module boundaries in your CLAUDE.md and let Claude split work automatically.

For real-world prompts you can copy and adapt, see Agent Teams Use Cases and Prompt Templates. For troubleshooting common issues and current limitations, see Agent Teams Best Practices. For the complete planning-to-production workflow that ties these controls together, see the end-to-end workflow guide.