// Parallel task orchestration CLI that dispatches work to AI workers (via Claude Code) in isolated git workspaces. Use when the user wants to draft, create, run, or manage tasks, delegate tasks to workers/subagents, or mentions subtask or Subtask.
| name | subtask |
| description | Parallel task orchestration CLI that dispatches work to AI workers (via Claude Code) in isolated git workspaces. Use when the user wants to draft, create, run, or manage tasks, delegate tasks to workers/subagents, or mentions subtask or Subtask. |
Subtask is a CLI for orchestrating parallel AI workers. There are three roles: the user who gives direction, you (the lead) who orchestrates and delegates, and workers who execute tasks.
Each worker runs in an isolated git worktree. They can't conflict with each other.
The user tells you what they need. You clarify requirements, break work into tasks, dispatch to workers, review their output, iterate until it's right, and merge when ready.
Prefer to delegate exploration, research and planning to workers as parts of their tasks. Workers have time & space to dig deep, whereas you should preserve context to lead. Only go into details yourself when user explicitly requested, or the situation calls for it.
| Command | Description |
|---|---|
subtask ask "..." | Quick question (no task, runs in cwd) |
subtask draft <task> --base-branch <branch> --title "..." <<'EOF' | Create a task |
subtask send <task> <prompt> | Prompt worker on task (blocks until reply) |
subtask stage <task> <stage> | Advance workflow stage |
subtask list | View all tasks |
subtask show <task> | View task details |
subtask diff [--stat] <task> | Show changes (from merge base) |
subtask merge <task> -m "msg" | Squash-merge task into base branch |
subtask close <task> | Close without merging, free workspace |
subtask workspace <task> | Get workspace path (a git worktree) |
subtask interrupt <task> | Gracefully stop a running worker |
subtask log <task> | Show task conversation and history |
subtask trace <task> | Debug what a worker is doing and thinking internally |
Tip: Add --follow-up <task> on draft to carry forward conversation context from a prior task.
# 1. Draft (task name is branch name, task description is shared with worker)
subtask draft fix/bug --base-branch main --title "Fix worker pool panic" <<'EOF'
There's an intermittent panic in the worker pool under high concurrencyโlikely a race condition in pool.go.
Reproduce, find root cause, fix, and add tests.
EOF
# 2. Start the worker
subtask send fix/bug "Go ahead."
# 3. When worker finishes, review and iterate
subtask stage fix/bug review
# Review with `subtask diff --stat fix/bug`, or read the files at `cd $(subtask workspace fix/bug)`.
# 4. Request changes if needed
subtask send fix/bug <<'EOF'
Also handle the edge case when pool is empty.
EOF
# 5. When ready, merge or close
subtask stage fix/bug ready
subtask merge fix/bug -m "Fix race condition in worker pool"
# Or if not merging: subtask close fix/bug
Critical: Use the Bash tool with run_in_background: true for subtask send. Tell the user you're waiting and stop. Don't poll or check. You'll be notified when done.
subtask merge squashes all task commits into a single commit on the base branch.
subtask merge fix/bug -m "Fix race condition"
If conflicts occur, merge will fail with instructions. Follow them.
All tasks have stages: doing โ review โ ready
| Stage | When to advance |
|---|---|
doing | Worker is working (default) |
review | Worker done, you're reviewing code |
ready | Ready for human to decide (human review, merge, more work, etc.) |
Advance with: subtask stage <task> <stage>
For complex tasks, add a plan stage: plan โ implement โ review โ ready
You plan (--workflow you-plan): You draft PLAN.md in task folder, worker reviews and pokes holes.
They plan (--workflow they-plan): Worker drafts PLAN.md in task folder, you review and approve or request changes.
subtask list to see whatโs in flight.subtask show <task> to see progress and details.subtask log <task> to see task conversation and events.subtask trace <task> to debug what a worker is doing and thinking internally.