Clusters & Execution

Visualize execution phases and launch autonomous Claude Code teams sessions

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

1. Open iTerm2 (macOS) — download here if you don’t have it
2. 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.
3. Run the command:
   tm clusters start --tag <tag>
   
   Or without a tag to execute the active tag:
   tm clusters start
   

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:

1. Task Master loads your tasks and detects clusters from the dependency DAG
2. An execution plan is built — showing clusters, task count, and estimated turns
3. The plan is displayed for review
4. Claude Code launches with a system prompt containing the full execution context
5. 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

---

Related documentation:

• CLI Root Commands — full command reference
• Loop Command — autonomous loop-based execution
• Task Structure — understanding task organization