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