Subtask
Dispatches parallel AI workers into isolated git worktrees via the subtask CLI
Test report
- Verdict
- Works with setup
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · ade466b
Built the Go CLI from source (go1.26.5) and ran everything under an mktemp HOME; the real ~/.claude/skills and ~/.subtask were verified untouched. All 13 commands the SKILL.md table lists (ask, draft, send, stage, list, show, diff, merge, close, workspace, interrupt, log, trace) exist in the binary, and `subtask install --no-prompt --scope user --harness claude` wrote SKILL.md to ~/.claude/skills/subtask/SKILL.md. Baseline artifact (/tmp/st-baseline): fixing two independent Python bugs my own way gave 2 sequential branches and `git worktree list` showing 1 entry, with no task metadata. Skill artifact (/tmp/st-skill2): following the body verbatim gave `git worktree list` with 3 entries (main + fix/duration-hours + feat/retry-validation live simultaneously at distinct paths), a .subtask/tasks/<task>/ folder per task holding TASK.md (title/base-branch frontmatter), WORKFLOW.yaml and history.jsonl, a `subtask list` status table showing both in flight with +1 -1 and +7 -3, and `subtask merge` squashing each onto main ("Merged ... Workspace freed") for a clean 2-commit main. The one step I could not execute is the actual AI worker: `subtask send` provisioned the worktree and dispatched, but the harness died in 3.6s and `subtask trace` showed the worker prompt answered with "Invalid API key - Please run /login" because the temp HOME has no credentials, so I hand-committed the worker output to test review/merge. Also hit an undocumented blocker: in a repo where /.subtask/ was not gitignored before drafting, `subtask merge` refused with "has uncommitted changes" (ensureGitignore is only called from `subtask config`, not `draft`). Security scan clean: SKILL.md has no URLs, scripts, base64 or injection text, and the optional plugin hooks only echo "consider loading the subtask skill" reminders.
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 5/5
- Triggers reliably 5/5
- Output vs. baseline 5/10
- Docs & honesty 4/5
What Subtask does
Teaches Claude Code to orchestrate parallel work through the `subtask` Go CLI: each task gets its own git worktree and branch, plus a task record with title, base branch and an event history. Covers the full loop of draft, send to a worker, review the diff, advance stages (doing to review to ready), and squash-merge back into the base branch. Triggers when the user asks to delegate work to workers or subagents, run several tasks in parallel, or mentions Subtask by name.
How to install Subtask
git clone --depth 1 https://github.com/zippoxer/subtask.git /tmp/subtask-src
mkdir -p ~/.claude/skills/subtask
cp /tmp/subtask-src/pkg/install/SKILL.md ~/.claude/skills/subtask/SKILL.md
# REQUIRED: the skill is a thin wrapper and does nothing without the `subtask` Go binary.
# brew install zippoxer/tap/subtask
# # or: go install github.com/zippoxer/subtask/cmd/subtask@latest
# # or: curl -fsSL https://subtask.dev/install.sh | bash (upstream install script; audit before running)
# Then configure the worker harness (writes the same SKILL.md itself, so the copy above is optional):
# subtask install --no-prompt --scope user --harness claude # or --harness codex / opencode
# # plain `subtask install` is interactive and fails without a TTY ("could not open a new TTY")
# REQUIRED: the chosen harness CLI (claude / codex / opencode) must be installed and authenticated,
# otherwise `subtask send` fails with "claude failed: exit status 1".
# Recommended: commit `/.subtask/` to .gitignore BEFORE drafting tasks, or `subtask merge` aborts
# with "has uncommitted changes" because .subtask/ is untracked inside each worktree.
# Optional plugin (adds hooks that remind Claude to load the skill):
# /plugin marketplace add zippoxer/subtask && /plugin install subtask@subtask
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger Subtask
-
/subtaskDispatches parallel AI workers into isolated git worktrees via the subtask CLI
It also activates on plain-language prompts like these:
-
Delegate this task to a subtask worker -
Run these three tasks in parallel workspaces -
Create a new subtask for this feature
Frequently asked questions
- Is the Subtask skill free?
- Yes. The skill itself is free from zippoxer/subtask. SkillProof publishes the install command and an independent test verdict at no cost.
- Does Subtask work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Works with setup. Built the Go CLI from source (go1.26.5) and ran everything under an mktemp HOME; the real ~/.claude/skills and ~/.subtask were verified untouched. All 13 commands the SKILL.md table lists (ask, draft, send, stage, list, show, diff, merge, close, workspace, interrupt, log, trace) exist in the binary, and `subtask install --no-prompt --scope user --harness claude` wrote SKILL.md to ~/.claude/skills/subtask/SKILL.md. Baseline artifact (/tmp/st-baseline): fixing two independent Python bugs my own way gave 2 sequential branches and `git worktree list` showing 1 entry, with no task metadata. Skill artifact (/tmp/st-skill2): following the body verbatim gave `git worktree list` with 3 entries (main + fix/duration-hours + feat/retry-validation live simultaneously at distinct paths), a .subtask/tasks/<task>/ folder per task holding TASK.md (title/base-branch frontmatter), WORKFLOW.yaml and history.jsonl, a `subtask list` status table showing both in flight with +1 -1 and +7 -3, and `subtask merge` squashing each onto main ("Merged ... Workspace freed") for a clean 2-commit main. The one step I could not execute is the actual AI worker: `subtask send` provisioned the worktree and dispatched, but the harness died in 3.6s and `subtask trace` showed the worker prompt answered with "Invalid API key - Please run /login" because the temp HOME has no credentials, so I hand-committed the worker output to test review/merge. Also hit an undocumented blocker: in a repo where /.subtask/ was not gitignored before drafting, `subtask merge` refused with "has uncommitted changes" (ensureGitignore is only called from `subtask config`, not `draft`). Security scan clean: SKILL.md has no URLs, scripts, base64 or injection text, and the optional plugin hooks only echo "consider loading the subtask skill" reminders.
- What is the Subtask SkillProof Score?
- 7.6/10 — installs cleanly 5/5, triggers reliably 5/5, output vs. baseline 5/10, docs & honesty 4/5.
- How do I install Subtask?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use Subtask with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.