Clusters & Execution

Task Master automatically detects execution clusters — groups of tasks that can run in parallel, sequenced by their dependency graph. The clusters command visualizes your execution topology, and clusters start launches an autonomous Claude Code session to execute the plan.

Recommended Setup

For the best experience with tm clusters start, use iTerm2 with tmux control mode. This gives Claude Code's agent teams the ability to open split panes and manage parallel work visually.

Step-by-step

Open iTerm2 (macOS) — download here if you don't have it
Start tmux in control mode:
```
tmux -CC
```
iTerm2 will open a native tmux integration window. This lets Claude Code spawn panes and tabs that iTerm2 manages natively — no raw tmux key bindings needed.
Run the command:
```
tm clusters start --tag <tag>
```
Or without a tag to execute the active tag:
```
tm clusters start
```

Tip: tmux -CC is iTerm2's "control mode" — it bridges tmux sessions with iTerm2's native tab/pane management. You get all the benefits of tmux (session persistence, pane splitting) with iTerm2's UI. Claude Code's agent teams leverage this to orchestrate parallel task execution across panes.

Visualizing Clusters

Before executing, use tm clusters to understand your project's execution topology.

Tag-level phases

Without a --tag flag, clusters shows your tags organized into execution phases:

tm clusters

Tags at the same level can run in parallel. Tags at higher levels depend on lower levels completing first.

Task-level clusters

Drill into a specific tag to see how its tasks are clustered:

tm clusters --tag backend

Each cluster groups tasks that share the same topological level — they have no dependencies on each other and can execute concurrently.

Output formats

Flag	Output	Use case
(default)	Table with cluster breakdown	Quick overview
`--tree`	ASCII dependency tree	Understanding task relationships
`--diagram mermaid`	Rendered Mermaid diagram in terminal	Visual dependency graph
`--diagram mermaid-raw`	Raw Mermaid syntax	Copy-paste into docs, PRs, or mermaid.live
`--json`	Raw JSON	Programmatic access

# Visual dependency graph
tm clusters --tag backend --diagram mermaid

# Raw Mermaid for embedding in docs
tm clusters --diagram mermaid-raw > execution-plan.mmd

Executing Clusters

`tm clusters start`

Builds an execution plan from your task graph and launches an interactive Claude Code session with agent teams enabled.

tm clusters start --tag <tag>

What happens:

Task Master loads your tasks and detects clusters from the dependency DAG
An execution plan is built — showing clusters, task count, and estimated turns
The plan is displayed for review
Claude Code launches with a system prompt containing the full execution context
Agent teams mode is enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), allowing Claude to spawn sub-agents for parallel task execution

CLI options

Option	Description
`-t, --tag <tag>`	Tag to execute (default: active tag)
`--dry-run`	Show execution plan without launching Claude
`--parallel <n>`	Max concurrent tasks per level (default: 5)
`--resume`	Resume from a previous checkpoint
`--continue-on-failure`	Keep going even if some tasks fail
`--json`	Output the execution plan as JSON
`-p, --project <path>`	Project root (auto-detected if not provided)

Dry run

Preview the execution plan without launching a Claude session:

tm clusters start --tag backend --dry-run

Resume from checkpoint

If a session is interrupted (Ctrl+C), Task Master saves a checkpoint automatically. Resume where you left off:

tm clusters start --tag backend --resume

Example Workflow

# 1. See the big picture -- tag-level execution phases
tm clusters

# 2. Drill into a tag
tm clusters --tag backend

# 3. Preview the execution plan
tm clusters start --tag backend --dry-run

# 4. Open iTerm2, start tmux control mode, and execute
tmux -CC
tm clusters start --tag backend