Configuring Agent Teams with tmux for Parallel Development on the Same Codebase

Claude Code enables multiple autonomous agents to work simultaneously on a single repository using tmux panes, eliminating merge conflicts while maintaining visual separation of each agent's workflow.

The shanraisshan/claude-code-best-practice repository documents how to configure agent teams with tmux for parallel development on the same codebase. This experimental feature allows multiple AI agents to share a single working tree, with each agent operating in its own tmux pane for true concurrent execution.

How Agent Teams Work in Claude Code

The teammateMode Configuration

According to best-practice/claude-settings.md, the teammateMode setting controls how agents are displayed. Valid values include:

• in-process: Single process display
• tmux: Split panes using tmux
• auto: Detects tmux or iTerm2 automatically

Shared State Architecture

When teammateMode is set to tmux or auto (on tmux-compatible terminals), Claude spawns a tmux session with one pane per teammate as documented in reports/claude-global-vs-project-settings.md. All agents operate on the same working tree, so changes made by one agent are instantly visible to others without requiring git worktrees or separate checkouts.

Enabling tmux Mode for Parallel Development

Environment Variable Activation

The experimental agent teams feature requires setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 as documented in best-practice/claude-cli-startup-flags.md.

CLI Configuration

Use the --teammate-mode flag to specify the display mode at launch:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude-code --teammate-mode tmux

For automatic detection, use --teammate-mode auto, which falls back to in-process if tmux is not detected.

Configuring tmux Sessions for Agent Teams

Pre-creating Pane Layouts

As noted in the repository's examples, you can configure tmux before launching Claude to ensure optimal pane distribution. A sample configuration from the documentation:

# Create a session called "claude" with horizontal splits for teammates

new-session -d -s claude
split-window -h
select-pane -t 0
attach-session -t claude

When Claude launches with teammateMode: tmux, it attaches to the existing session or creates panes within your configured layout.

Leveraging Hooks for Team Coordination

Lifecycle Event Hooks

The .claude/hooks/HOOKS-README.md file documents hooks that fire independently for each teammate, enabling coordination without blocking:

• TeammateIdle: Fires when an agent becomes idle
• TaskCompleted: Fires when a teammate finishes a task

Asynchronous Hook Configuration

Hooks run concurrently for each teammate. Example configuration:

on:
  TaskCompleted:
    async: true
    timeout: 5000
    script: |
      echo "Teammate {{teammate_name}} finished {{task_subject}}"
      # Trigger downstream tasks or notifications here

Because hooks execute asynchronously, the main workflow never blocks while waiting for individual teammates, maintaining the parallel execution model.

Summary

• Agent teams enable multiple Claude instances to work concurrently on a single codebase using CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• tmux mode (teammateMode: tmux or auto) provides visual separation via split panes while maintaining shared state across all agents.
• Configuration is controlled via best-practice/claude-settings.md settings or --teammate-mode CLI flags documented in best-practice/claude-cli-startup-flags.md.
• Pre-configured tmux sessions can optimize pane layouts before launching Claude Code.
• Lifecycle hooks (TeammateIdle, TaskCompleted) in .claude/hooks/HOOKS-README.md enable asynchronous coordination between parallel agents.

Frequently Asked Questions

What is the difference between tmux and auto teammate modes?

The tmux mode forces Claude Code to use tmux panes regardless of terminal detection, while auto mode automatically detects if you are running inside tmux or iTerm2 and selects the appropriate display method. If no compatible terminal multiplexer is detected, auto falls back to in-process mode.

Do I need separate git worktrees for each agent when using tmux mode?

No. One of the primary advantages of the tmux-based agent team configuration is that all agents share a single working tree. Since all panes operate within the same repository checkout, changes made by one agent are immediately visible to others without requiring git worktrees or separate clones.

How do I prevent hooks from blocking other agents?

Configure hooks with async: true in your .claude/hooks/ configuration files. According to the HOOKS-README.md documentation, asynchronous hooks execute independently for each teammate, ensuring that lifecycle events like TaskCompleted never block the main workflow or other parallel agents.

Can I use tmux mode without the experimental environment variable?

No. The CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable is required to enable the agent teams feature itself. Without this variable set, Claude Code will not spawn multiple agents regardless of the teammateMode setting or --teammate-mode CLI flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}