Skip to content
/
Tier B A6 Multi-agent orchestrator

Subtask

subtask-zippoxer · zippoxer/subtask · ★ 330 · last commit 2026-04-27

Primitive shape 1 total
Skills 1
00

Summary

Subtask (zippoxer) — Summary

Subtask is a Go CLI + Claude Code skill that gives a lead AI agent the ability to create tasks, spawn worker subagents in isolated git worktrees, track progress, review results, and merge — all orchestrated by the lead without user involvement. The lead agent (e.g., Claude Code) runs subtask draft, subtask list, subtask review, and subtask merge CLI commands; worker agents (Claude, Codex, or OpenCode) receive task prompts via a harness and run in separate git worktrees.

The system uses file-based state (.subtask/tasks/<name>/) with an event-sourced history.jsonl as the source of truth and an optional SQLite index as a derived projection for fast queries. A TUI (subtask in terminal) shows progress, diffs, and conversation history. Subtask explicitly claims it was "built with Subtask" — the repo itself was developed using the workflow it describes.

Compared to seeds: architecturally closest to superpowers (git worktrees + subagent dispatch), but Subtask ships a dedicated Go CLI binary as the coordination layer rather than relying on Claude's internal Task tool. Unlike claude-flow (MCP-anchored hive-mind), Subtask is git-native and local-first with no external service dependency.

01

Overview

Subtask (zippoxer) — Overview

Origin

Built by the repo author (zippoxer) as a self-hosted parallel task management tool for AI coding agents. Released as MIT. Explicitly claims to have been developed using its own workflow: "~60 tasks merged in the past week" with Claude Code as lead and Codex for workers.

Philosophy

Without Subtask, a user managing multiple AI coding sessions must open multiple terminal tabs, mentally track each session's context, juggle progress and blockers, and re-explain context when sessions crash. "The user becomes a human orchestrator for AI workers."

Subtask shifts this cognitive burden from user to lead agent:

  • User: Gives direction, makes decisions, approves work
  • Lead (e.g., Claude Code): Orchestrates everything in between
  • Workers: Execute tasks in parallel, isolated in git worktrees

"The lead is not a task dispatcher. The lead is a technical lead / project manager."

Design Decisions (From CLAUDE.md)

  1. Task-centric — Task name is the primary identifier. Everything flows from it.
  2. Git-native — Branches for isolation, worktrees for parallelism, standard merge workflow.
  3. File-based collaboration — Task folder shared between lead and worker. PLAN.md for plans, PROGRESS.json for tracking. Files persist; sessions don't.
  4. Workspace opacity — Lead never picks workspaces. Subtask assigns them.
  5. Context preservation — history.jsonl ensures nothing is lost when sessions crash.
  6. Progress visibility — Tool counts, timing, and PROGRESS.json let lead track workers without interrupting them.
  7. Guardrails over escape hatches — Errors guide the lead on what to do next, not just fail.
  8. Event sourcing — history.jsonl is the append-only source of truth. SQLite is a derived projection; if they diverge, history wins.

Explicit Antipatterns

  • User becoming the human orchestrator for AI workers
  • Opening multiple terminal tabs to track parallel work
  • Ralph loop (continuous daemon) — "Ralph not needed"
02

Architecture

Subtask (zippoxer) — Architecture

Distribution

  • Type: CLI tool (Go binary) + Claude Code skill
  • License: MIT
  • Install complexity: multi-step (CLI binary + skill install)

Install Commands

# Mac/Linux
curl -fsSL https://subtask.dev/install.sh | bash

# Homebrew
brew install zippoxer/tap/subtask

# Go
go install github.com/zippoxer/subtask/cmd/subtask@latest

# Skill install (after CLI)
subtask install --guide   # guided install
# Or in Claude Code:
/plugin marketplace add zippoxer/subtask
/plugin install subtask@subtask

Directory Layout

cmd/subtask/            # Go CLI source (~50 command files)
pkg/
├── task/               # Task data model
├── workflow/           # Workflow state machine
├── git/                # Git operations
├── harness/            # Worker harness (Claude/Codex/OpenCode)
├── workspace/          # Git worktree pool management
├── tui/                # Terminal UI
└── logging/            # history.jsonl event sourcing

.subtask/tasks/         # Per-task portable folders
  <task-name>/
    TASK.md             # Task description
    PLAN.md             # Plan (optional)
    PROGRESS.json       # Worker progress tracking
    history.jsonl       # Append-only event log (source of truth)
.subtask/internal/<task>/   # Runtime/machine-specific state
.subtask/index.db           # SQLite derived index (non-authoritative)

~/.subtask/workspaces/      # Git worktree pool (global)

Data Model Key Detail

  • Task name fix/epoch-boundary → folder .subtask/tasks/fix--epoch-boundary/ (escaped with --)
  • Task folder is the portable, syncable unit — copy anywhere and full context follows
  • history.jsonl is append-only (event sourcing); SQLite index is a cache derived from it

Required Runtime

  • Go (for building from source) or prebuilt binary
  • git

Target AI Tools

  • Claude Code (primary as lead)
  • Codex (worker)
  • OpenCode (worker)
03

Components

Subtask (zippoxer) — Components

CLI Commands (Go binary — invoked by lead agent)

Command Purpose
subtask draft <name> [description] Create a new task draft with a description
subtask list List all tasks with status
subtask show <name> Show task details, PROGRESS.json, conversation
subtask send <name> [message] Send a follow-up message to a worker
subtask ask <name> [question] Ask a worker a question (interrupt)
subtask review <name> Review worker output and diff
subtask stage <name> Stage task for merging
subtask merge <name> Merge task branch
subtask close <name> Close a task
subtask revive <name> Restart a failed/stalled task
subtask diff <name> Show task diff
subtask log <name> Show task log
subtask logs <name> Show full logs with working sessions
subtask interrupt <name> Interrupt a running worker
subtask status Overall project status
subtask install Install skill and configure
subtask uninstall Remove skill and clean up
subtask update Update CLI
subtask config Configure settings (wizard or direct)

Skills

Name File Purpose
Subtask (Claude Code skill) ~/.claude/skills/subtask/ Provides Claude with knowledge of CLI, task lifecycle, and orchestration patterns

Plugin

Name File Purpose
Subtask plugin .claude-plugin/ Reminds Claude to use the Subtask skill when it invokes the CLI

State Files

File Purpose
.subtask/tasks/<name>/TASK.md Task description
.subtask/tasks/<name>/PLAN.md Optional plan
.subtask/tasks/<name>/PROGRESS.json Worker progress (tool counts, timing)
.subtask/tasks/<name>/history.jsonl Append-only event log (source of truth)
.subtask/index.db SQLite derived index (non-authoritative)
~/.subtask/workspaces/<escaped-path>--<id>/ Git worktree pool

TUI

Run subtask in terminal to see task list, progress, diffs, and conversations.

05

Prompts

Subtask (zippoxer) — Prompt Excerpts

Excerpt 1: Role Definition (from CLAUDE.md)

Technique: Three-actor role separation with explicit responsibility boundaries

### The Solution

Subtask shifts the cognitive burden from user to lead agent.

**Three roles:**
- **User**: Gives direction, makes decisions, approves work
- **Lead** (e.g., Claude Code): Orchestrates everything in between
- **Workers**: Execute tasks in parallel, isolated in git worktrees

The user provides direction. The lead handles everything else: understanding requirements, breaking work into tasks, dispatching to workers, tracking progress, reviewing output, iterating until it's right, merging when ready.

The lead is not a task dispatcher. The lead is a technical lead / project manager.

Analysis: The three-actor model sets clear responsibilities and prevents the common failure mode where the AI agent becomes a dispatcher rather than a decision-maker. The "technical lead / project manager" framing sets a higher behavioral bar than "dispatcher."

Excerpt 2: Design Decisions (from CLAUDE.md)

Technique: Numbered design principles as architectural constraints

## Design Decisions

1. **Task-centric** — Task name is the primary identifier. Everything flows from it.
2. **Git-native** — Branches for isolation, worktrees for parallelism, standard merge workflow.
3. **File-based collaboration** — Task folder shared between lead and worker. PLAN.md for plans, PROGRESS.json for tracking. Files persist; sessions don't.
4. **Workspace opacity** — Lead never picks workspaces. Subtask assigns them.
5. **Context preservation** — history.jsonl and --follow-up ensure nothing is lost when sessions crash.
6. **Event sourcing** — history.jsonl is the append-only source of truth. SQLite index is a derived projection. If they diverge, history wins.

Analysis: Design decisions are expressed as invariants, not preferences. "Lead never picks workspaces" and "if they diverge, history wins" are absolute rules, not guidelines. This is an Iron Law pattern applied to infrastructure design.

Excerpt 3: CLI Usage Example (from README)

Technique: Concrete dialogue trace showing the exact CLI invocations

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.

Analysis: The diagram format shows the lead agent's actual behavior as a trace tree, not prose. This is a behavioral contract: exactly which commands get called, in what order, with what result. The ⏺ symbol for "awaiting notification" is meaningful — the lead is not polling, it is event-driven.

09

Uniqueness

Subtask (zippoxer) — Uniqueness & Positioning

Differs From Seeds

Closest seeds: superpowers (git worktrees + subagent dispatch) and claude-flow (parallel agents + task management). But Subtask differs from both: unlike superpowers, Subtask ships a dedicated Go CLI binary as the coordination layer rather than relying on Claude's internal Task tool. Unlike claude-flow's MCP-anchored hive-mind (SQLite + HNSW vector memory, 305 MCP tools, Byzantine consensus), Subtask is intentionally local-first, git-native, and file-based with no external service dependency — "history wins" over any derived index.

The interrupt/communication capability ("Claude can interrupt and talk with subagents!") is also distinct from both seeds — superpowers dispatches and awaits, claude-flow uses memory-based coordination. Subtask's subtask send/ask enables bidirectional mid-execution communication between lead and worker.

Observable Failure Modes

  1. Early development stage: README explicitly notes "Subtask is in early development. Upcoming releases will simplify installation, solve known bugs."
  2. Go binary dependency: Users unfamiliar with Go toolchain may struggle with non-script install.
  3. Worktree pool management: Stale worktrees under ~/.subtask/workspaces/ may accumulate disk space.
  4. Worker harness configuration: Must configure which agent (Claude/Codex/OpenCode) runs workers at install time — not dynamically switchable per task.
  5. No web UI: Power users wanting a dashboard must use the TUI.

Distinctive Opinion

The user should be a product owner, not a project manager. Once the user gives direction, the lead agent should handle all coordination: task decomposition, worker dispatch, progress tracking, review, and merging — with the user only re-engaged for final approval.

Self-Referential Proof

The repo claims to be built using its own workflow: Claude Code as lead, Codex as workers, ~60 tasks merged per week. This "eating its own dog food" claim is verifiable via the repo's commit history.

04

Workflow

Subtask (zippoxer) — Workflow

Task Lifecycle Phases

Phase Actor Action Artifact
1. Direction User Tells lead agent what to build Natural language
2. Task Creation Lead (Claude Code) subtask draft <name> <description> × N .subtask/tasks/<name>/TASK.md
3. Worker Dispatch Lead Subtask assigns workspace (worktree), starts worker harness Worker running in isolated worktree
4. Execution Worker (Codex/Claude/OpenCode) Implements task, updates PROGRESS.json Modified code in worktree
5. Notification Subtask CLI Notifies lead when worker completes or replies Event in history.jsonl
6. Review Lead subtask review <name> — examines diff and output Review decision
7. Iterate or Merge Lead Sends follow-up (subtask send) or merges (subtask merge) Merged branch
8. Completion User Sees result; approves merge or requests further changes Final code

Task Statuses

draft → working → replied → staged → merged / closed

Approval Gates

  1. Review gate: Lead reviews worker output before staging
  2. Merge gate: Lead stages task then merges (two-step — prevents accidental merge)
  3. User approval: User can ask lead to merge or request changes at any point

Parallel Execution

Multiple tasks execute simultaneously in separate git worktrees. The lead tracks all of them via subtask list without interrupting workers.

Interrupt / Follow-up

  • subtask send <name> <message> — adds a message to the running worker's context
  • subtask ask <name> <question> — asks a question; worker responds in the conversation

This is described as the key differentiator: "Claude can interrupt and talk with subagents!"

Event Sourcing

All state changes append to history.jsonl. The SQLite index is rebuilt from history if it diverges. This makes task folders portable and crash-recoverable.

06

Memory Context

Subtask (zippoxer) — Memory & Context

State Storage

File-based, project-scoped. The .subtask/ directory is the primary state store.

Persistence Architecture

Two-tier:

  1. Portable tier — .subtask/tasks/<name>/ — portable, syncable task folders
    • history.jsonl — append-only event log (authoritative source of truth)
    • TASK.md, PLAN.md, PROGRESS.json — human/agent readable state
  2. Runtime tier — .subtask/internal/<task>/ — machine-specific cache, rebuildable
  3. Workspace pool — ~/.subtask/workspaces/<escaped-project-root>--<id>/ — git worktrees (global)
  4. SQLite index — .subtask/index.db — derived projection for fast queries (non-authoritative)

Event Sourcing Pattern

history.jsonl is append-only. All state changes are recorded as events. If the SQLite index diverges from history, history wins. This makes task folders crash-recoverable: copy the task folder to another machine and full context is available.

Cross-Session Handoff

Yes — this is a primary design goal. Task folders persist across session crashes, context window resets, and agent restarts. The worker can be interrupted and restarted without losing progress. --follow-up flag preserves context across restart.

Context Per Worker

Each worker sees the repository and its own task folder. It cannot see:

  • CLI output
  • Other tasks
  • Lead's orchestration state

Memory Type

File-based + SQLite (cache). No vector DB, no external memory service.

07

Orchestration

Subtask (zippoxer) — Orchestration

Multi-Agent Pattern

Pattern: hierarchical (lead + workers in git worktrees)

Lead agent (Claude Code) orchestrates multiple worker agents. Workers execute in isolated git worktrees. Lead communicates with workers via subtask send/ask and monitors via subtask list/show.

Isolation Mechanism

Git worktrees — each task gets its own git worktree under ~/.subtask/workspaces/. Workers cannot see each other's changes until merged.

Execution Mode

Parallel fan-out — multiple workers execute simultaneously in separate worktrees. Lead is event-driven (notified on completion) rather than polling.

Subagent Definition Format

Workers are not defined as persona-md or code-class files — they are spawned via the CLI harness (subtask install configures which harness to use: Claude, Codex, or OpenCode). The lead agent calls subtask draft and Subtask CLI launches the worker harness.

Multi-Model

Yes, across the lead/worker boundary:

  • Lead: typically Claude Code (reasoning, orchestration)
  • Workers: configurable at install time — Claude, Codex, or OpenCode

No model routing within a single role.

Commit / PR Automation

Workers commit to their branches. Lead can subtask merge to merge via standard git. No auto-PR creation. No auto-merge without lead approval.

Event-Driven Notification

Lead receives notifications when workers complete or reply. The lead does not poll — it is notified and then decides the next action. This prevents the busy-wait pattern.

Consensus Mechanism

None — lead makes all merge/approval decisions unilaterally.

08

Ui Cli Surface

Subtask (zippoxer) — UI / CLI Surface

CLI Binary

Yes — subtask (Go binary).

  • Not a thin wrapper: own runtime with full task lifecycle management
  • Subcommands: draft, list, show, send, ask, review, stage, merge, close, revive, diff, log, logs, interrupt, status, install, uninstall, update, config
  • Install: curl install script, Homebrew, go install

TUI (Terminal UI)

Yes — run subtask (no subcommand) to launch the TUI.

  • Built with Go TUI library
  • Shows: task list with status columns (TASK / STATUS / TITLE)
  • Shows: diffs for each task
  • Shows: conversation history between lead and worker
  • Not a web dashboard — runs in the terminal

IDE Integration

  • Claude Code: skill + plugin (skill teaches Claude to use the CLI; plugin reminds Claude when appropriate)
  • Codex: supported as worker agent
  • OpenCode: supported as worker agent

Observability

  • subtask list — tabular view of all tasks with status
  • subtask show <name> — detailed view including PROGRESS.json (tool counts, timing)
  • history.jsonl — full event log per task (human-readable)
  • TUI — live view without interrupting workers
  • No web dashboard, no hosted monitoring

Auto-Update

subtask update --check / subtask update — built-in update mechanism.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…