Subtask ✨

Fork of zippoxer/subtask, maintained by kgruel since v0.3.0. Adds config-driven adapters, Gemini and pi worker support, and per-task adapter overrides.

Subtask gives your coding agent (Claude Code, pi, Codex CLI, opencode, Gemini CLI — any lead) a Skill and CLI to create tasks, spawn subagents, track progress, review and request changes.

• Each task gets a Git worktree, so they can be done in parallel safely
• Your lead agent can interrupt and talk with subagents!
• TUI shows progress, diffs & conversations
• Tasks are persisted in folders
• Codex, opencode, Gemini, and pi subagents supported
• Ralph not needed

Spawning Tasks

You: fix the auth bug and add API metrics with Subtask

Claude:
  ├─► Skill(Subtask)
  ├─► Bash(subtask draft fix/auth-bug ...)
  ├─► Bash(subtask draft feat/api-metrics ...)
  └─⏺ Tasks are in progress! I'll get notified when they're done.

Tracking & Merging

You: which tasks are open?

Claude:
  ├─► Bash(subtask list)
  │   ┌──────────────────┬─────────┬────────────────────────┐
  │   │ TASK             │ STATUS  │ TITLE                  │
  │   ├──────────────────┼─────────┼────────────────────────┤
  │   │ fix/auth-bug     │ replied │ Fix auth token refresh │
  │   │ feat/api-metrics │ working │ Add API metrics        │
  │   │ feat/ui-redesign │ draft   │ Redesign dashboard     │
  │   └──────────────────┴─────────┴────────────────────────┘
  │
  └─⏺ ui-redesign hasn't started yet — want me to kick it off?

You: lets merge fix/auth-bug.

TUI

Run subtask in your terminal to see everything:

Setup

Note

Subtask is in early development. Upcoming releases will simplify installation, solve known bugs, and improve Claude's proficiency.

Install the CLI

Go

go install github.com/kgruel/subtask/cmd/subtask@latest

Binary

GitHub Releases

Install the lead integration

Tell your lead agent:

Setup Subtask with `subtask install --guide`.

It will run subtask install --guide, which detects lead-capable CLIs on your machine, has the agent pick itself (--lead <name>), and asks whether subagents should run Claude, Codex, opencode, Gemini, or pi.

Delivery depends on the lead: Claude Code and pi each get their own whole-file Skill copy of the instructions (same content, written verbatim to each CLI's skills dir). Codex CLI, opencode, and Gemini CLI instead get a small managed section in their always-loaded context file (AGENTS.md / GEMINI.md) that points at one canonical copy of the instructions, ~/.subtask/SKILL.md.

Or install manually…

# Interactive: multi-select which leads to install for
subtask install

# Non-interactive: install for a specific lead
subtask install --lead claude --no-prompt

# Tip: Uninstall later with `subtask uninstall`.

Install the Plugin (Optional)

Claude-Code-specific enhancement (hooks: unread-reply guard, stale-worker warning). Installed automatically whenever claude is among the selected leads; skip it with --no-plugin. For a marketplace install instead:

/plugin marketplace add kgruel/subtask
/plugin install subtask@subtask

This reminds Claude Code to use the Subtask skill when it invokes the CLI.

Use

Talk with your lead agent about what you want done, and then ask it to use Subtask.

Example: "fix the login bug with Subtask"

What happens next:

1. Your lead agent creates tasks and runs subagents to do them simultaneously.
   
2. It gets notified when they're done, and reviews the code.
   
3. It asks if you want to merge, or ask for changes.

Updating

subtask update --check
subtask update

License

MIT \n