uberclaw

UberClaw

Mission-driven multi-Claude orchestrator: spawn, coordinate, and budget child Claude Code sessions from a single declarative mission. UberClaw treats one mission file as the source of truth, runs 3-8 headless claude -p --bare children in parallel, aggregates their token spend, resolves their conflicts against the mission text, and only interrupts the human on real escalations.

Setup guide

UberClaw runs on macOS and Linux only. Windows is out of scope for v1 (we rely on fcntl and POSIX subprocess semantics). The plugin is tested against claude CLI v2.1.32 and newer; older versions may work but the headless flag set is unpinned upstream.

Prerequisites:

• claude CLI on PATH (claude --version).
• Python 3.11 or 3.12.
• uv for the helper toolchain.

Two install paths:

1. Plugin install (preferred for end users):

   claude plugin install uberclaw@<marketplace>
   

2. Local dev (clone, point Claude Code at the directory, sync the helper):

   git clone https://github.com/<org>/uberclaw.git
   cd uberclaw
   claude --plugin-dir .
   
   # In a second shell, prepare the Python helper:
   cd python && uv sync
   

After install, run a sanity check inside any Claude Code session:

/uberclaw:status

It should print no active run.

Optional one-time training pass. UberClaw can inventory the skills, agents, and commands you already use and prefer them when delegating subtasks:

/uberclaw:train

train is idempotent and never modifies the source ~/.claude/ or ./.claude/ files. It writes a per-project Markdown profile to <project>/.claude/uberclaw/profile.md (user-editable, commitable). The ## User notes section is preserved across runs.

Usage guide

Quickstart:

# 1. Copy the mission template into your project
cp missions/DEFAULT.md goals.md

# 2. Edit goals.md (set mission_id, priority, budget, human_checkpoints)
$EDITOR goals.md

# 3. Inside Claude Code, kick off the orchestrator
#    (no args -> picks up ./goals.md, falls back to ./mission.md)
/uberclaw:uberclaw

Mission file anatomy. The canonical filename is goals.md (mission.md is also accepted). A minimal mission:

---
mission_id: saas-mvp
priority: speed
budget:
  usd_hard: 50.00
  usd_warn: 30.00
  tokens_hard: 5_000_000
  children_max: 6
  turn_max: 60
human_checkpoints:
  - "before any production deploy"
  - "before deleting a database"
# Optional override; default is the Claude Code alias `opus[1m]`.
# model: opus[1m]
---

# Goal
...

The default child model is the Claude Code alias opus[1m] ("Opus, 1M-token context window"). Override priority: --model flag > brief frontmatter model: > mission frontmatter model: > UBERCLAW_CHILD_MODEL env > opus[1m].

Slash commands:

• /uberclaw:uberclaw [<mission-text>|<path>] — kick off an orchestrated run. With no argument, loads ./goals.md (or ./mission.md if the former is absent).
• /uberclaw:status [--child <id>] — print the active run's state summary.
• /uberclaw:stop [--child <id>] — halt all children for the active run, soft by default.
• /uberclaw:train [--global] — inventory ~/.claude/{skills,agents,commands} and ./.claude/{skills,agents,commands} into a per-project Markdown profile at <project>/.claude/uberclaw/profile.md. The ## User notes section is preserved across runs so you can hand-edit and commit it. Pass --global to write to ${HOME}/.claude/uberclaw/profile.md for cross-project knowledge.

Budgets and escalations. The mission's budget block (PRD §4.5) is enforced by uberclaw-helper budget. When usd_warn or tokens_hard thresholds are crossed, the watch monitor emits a budget_warn/budget_breach notification into your terminal. Hard breaches stop all children. The four human-escalation triggers (PRD §4.8) — hard budget breach, human_checkpoints substring match, irreversible action requested, ambiguous mission — surface in the orchestrator session as a prompt that quotes the mission, presents the conflicting evidence, lists three concrete options, and names a recommended option.

Where state lives. Each run gets a directory under ${CLAUDE_PLUGIN_DATA}/runs/<run-id>/:

runs/<run-id>/
  ├── mission.md           (byte-identical copy of the input)
  ├── state.json           (children, budget totals, run status)
  ├── decisions.jsonl      (every orchestrator decision, mission-quoted)
  ├── children/<id>.jsonl  (per-child stream-json events)
  └── lock                 (fcntl advisory lock file)

You can inspect any of these directly without the slash commands.

Troubleshooting: