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

> Streamline parallel development with Claude Code and tmux. Configure agent teams on a single codebase, eliminate merge conflicts, and visualize individual workflows without hassle.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: how-to-guide
- Published: 2026-03-12

---

**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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-cli-startup-flags.md).

### CLI Configuration

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

```bash
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:

```tmux

# 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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:

```yaml
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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md) settings or `--teammate-mode` CLI flags documented in [`best-practice/claude-cli-startup-flags.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.