Claude Code Agent Teams - From Setup to Shortcuts

Claude Code Agent Teams shipped alongside the Opus 4.6 release. Honestly, I find the feature inefficient at this stage - token consumption is high and coordination overhead is real.

But after reading Tom (@tomcrawshaw01)‘s guide, I realized the architecture itself is worth understanding. Getting familiar with it during the preview phase will make a difference when it goes GA.

Solo Agents Now Build Teams

A lead agent breaks down work and distributes it across multiple teammates running in parallel.

The key difference from sub-agents: teammates message each other directly. Instead of just reporting results back to the lead, they share findings and even challenge each other’s work.

Setup Takes 30 Seconds

The feature is experimental, so it’s off by default. One line enables it.

Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS with value "1" to the env block in your settings.json. You can also set it as a shell environment variable, but settings.json persists across sessions and is more convenient.

The Only Shortcuts You Need

Once a team is running, you’ll switch between the lead and teammates to monitor progress. There isn’t much to memorize.

• Shift+Up / Shift+Down - Switch between teammates (in-process mode - this is what you’ll use most of the time)
• Enter - View selected teammate’s session details
• Escape - Interrupt the selected teammate’s current turn
• Ctrl+T - Toggle the shared task list
• Shift+Tab - Toggle Delegate mode, which locks the lead to coordination only (no coding)
• Split-pane mode - Click on a teammate panel to interact directly

Delegate mode matters. Without it, the lead will sometimes start coding instead of delegating to teammates.

Terminal Compatibility Varies

Split-pane mode only works in tmux and iTerm2. VS Code’s integrated terminal, Windows Terminal, and Ghostty are officially unsupported.

If you’re working in Ghostty, you’ll use the default in-process mode with Shift+Up/Down to switch between teammates.

To see teammate output side by side, run Claude Code inside a tmux session. The default teammateMode is "auto", so it automatically switches to split-pane when it detects tmux.

I’ve been running tmux new -s {my-project} in iTerm, then launching with claude --teammate-mode tmux. This gives a full-screen view of all team activity.

How Tasks Flow

Work is organized around a task list. The lead creates tasks and teammates pick them up.

• When the lead creates a task list, teammates automatically claim the next unassigned task
• Dependencies between tasks are supported - successor tasks unlock only after predecessors complete
• You can assign specific tasks to specific teammates by telling the lead
• Teammate shutdown follows a protocol: lead sends a shutdown request, teammate confirms, then exits
• Full cleanup: confirm all teammates have shut down, then instruct the lead to clean up

A simple prompt that mentions “team” will activate the feature automatically. But for more precise control, define the total number of teammates, assign names and roles to each one, set delegation scope, and provide an external file with dependency rules between tasks.

Tokens Drain Faster Than You’d Expect

Each teammate is an independent Claude Code session. Running them in parallel escalates costs quickly. A few practices help.

• Write specific spawn prompts for teammates. The lead’s conversation history doesn’t carry over - only CLAUDE.md and MCP server context load automatically
• Two teammates editing the same file will cause overwrites. Partition work at the file level
• Start with research or code review rather than code generation. Coordination complexity is lower
• Keep task units small and concrete - a single function or a single test file works well

Limitations Worth Knowing Before You Hit Them

This is a preview. Rough edges are expected. Knowing them in advance saves frustration.

• Using /resume or /rewind kills in-process teammates. You’ll need to tell the lead to spawn new ones
• Task status can lag. If a teammate finishes work but doesn’t mark the task complete, successor tasks stay blocked. Check manually and ask the lead to update
• Only one team per session. Teammates cannot create sub-teams
• The session that creates the team stays the lead. You can’t swap leaders or promote teammates mid-session

The preview is rough and the cost-efficiency question remains open. But if you want to understand where multi-agent workflows are heading, the fastest way is to turn it on and try it yourself. Tools require hands-on experience to evaluate properly.