oh-my-subagents

Oh My Subagents

Turn ad-hoc subagents into durable, accountable AI teams.

Local subagent orchestration for Codex and Claude, with persistent task state, reusable teams, and interruption recovery.

Get started · Documentation · Starter teams

▶ Watch the tutorial

🚀 Stop babysitting subagents

Start with the Codex team guide, Claude team guide, or a concrete independent code-review workflow.

Ad-hoc delegation is easy to begin and surprisingly hard to operate. A parent spawns children, polls them, reconstructs ownership from chat, and hopes that a closed terminal or interrupted provider session did not erase the only useful account of what happened.

Oh My Subagents moves that coordination into durable runtime state:

Ad-hoc subagents	Oh My Subagents
Recreate roles and prompts for every job	Publish a reusable tree of named responsibilities
Keep asking whether every child is done	Let the runtime persist the wait, collect the complete Wave, and continue the parent
Reconstruct ownership from a transcript	Follow controller-owned team, Activity, and wait state
Treat provider completion as success	Accept only the Task lead's completed or blocked Result
Recover by piecing together terminal sessions	Recover from committed controller records without discarding accepted history
Relay giant responses through chat	Hand off concise Checkpoints and explicit references to ordinary workspace files

⚙️ How it works

When a Manager delegates a Wave, Oh My Subagents (OMS) commits the child Assignments, persists the parent wait, supervises every return, and continues the parent with the complete Checkpoints—even after an interruption.

The parent does not remain in a polling loop. A delegated Wave and its child Assignments commit together with the parent wait. Children return terminal Checkpoints independently; the controller collects the complete Wave and continues the parent with every return.

Managers can delegate recursively. Every Manager follows the same local rule with its direct children: delegate, wait, inspect the complete returns, and integrate. Deeper teams need no hidden global polling loop.

🧪 A concrete bug-fix run

Here is one concrete run: evidence determines the next Wave, review findings become a new repair Assignment, and verification remains independent.

🧠 Reuse responsibility—not a frozen schedule

A Workflow definition answers who is responsible. It does not prescribe when a Member runs or force the work into a DAG.

At runtime, Managers choose the pattern that fits the actual Task and current evidence:

• run dependent work sequentially;
• fan independent work out in parallel;
• iterate through implement, review, and repair;
• divide a bounded batch among reusable owners;
• combine those patterns in one Task; or
• replan one responsibility subtree when the current team no longer fits.

The same published team can therefore respond differently to two different missions. A replan changes future responsibility without rewriting earlier revisions, completed work, or accepted history.

🧾 Accountability is a runtime contract

OMS does more than display several agents at once:

• One stable starting contract. Every Task pins the exact published Workflow revision it started with.
• One owner per Assignment. Child work is immutable, task-specific, and tied to the Member responsible for returning it.
• Durable fan-out and fan-in. Waves, waits, retries, replans, Checkpoints, and continuations live in controller-owned state—not only in a provider transcript.
• One accountable Result. Child completion is evidence for a parent. Only the Task lead's accepted completed or blocked Checkpoint becomes the Result shown to you.
• Honest recovery. Browser closure, provider interruption, and controller restart do not silently fabricate completion or discard accepted history.
• Ordinary files stay ordinary. Notes, reports, code, and artifacts remain in your workspace. OMS records small navigation references instead of pretending to own or snapshot every byte.

Capabilities deny by default and never inherit from a parent. Provider, model, sandbox, Human Request, and managed Command Run choices stay explicit where a team needs them without becoming mandatory ceremony for every Workflow.

🎛️ Design and operate visually

The visual Console is the primary experience:

• Workflow library keeps reusable teams, drafts, and published revisions together.
• Workflow Studio lets you shape the complete responsibility hierarchy on a horizontal canvas, validate it, and publish deliberately.
• Run Studio shows the live team, current plans, meaningful Activity, Human Requests, managed Actions, referenced files, and the exact completed or blocked Result.
• Steering delivers bounded new context to one exact active Member without pretending earlier work or tool effects never happened.

Prefer conversation? The separate Operator can draft and revise Workflows, explain teams, publish when asked, start and control Runs, answer Human Requests, and inspect managed Actions. Operator and the visual interface call the same controller-owned operations, so chat never creates a second hidden copy of product truth.

⚡ Install and start

Oh My Subagents requires Python 3.12 or newer and supports Linux, macOS 13+, and Windows 11 x64. Install it in an isolated environment with [pipx](https: