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:

Failure	Fix
claude rejects the resolved model (e.g. older provider doesn't have opus[1m]).	Set UBERCLAW_CHILD_MODEL=<supported-model> or set model: in the mission frontmatter.
claude: command not found when running bin/uberclaw-spawn.	Install the Claude Code CLI and ensure it is on PATH.
mission frontmatter parse error.	Confirm the mission opens with ---\n...\n--- and that mission_id, priority, budget, human_checkpoints are present (PRD §4.5).
refusing to recurse: UBERCLAW_RUN_ID=<id> is already set (exit code 3).	The no-self-invocation guard fired. If you are in a fresh shell after a crash, run unset UBERCLAW_RUN_ID. Do not invoke /uberclaw:uberclaw from inside a child or from itself.

How it works

UberClaw is a Claude Code plugin: skills, monitors, and bin/ wrappers around a single Python helper (uberclaw-helper). The orchestrator skill (/uberclaw:uberclaw) loads the mission, plans a brief per child, and calls bin/uberclaw-helper init, then bin/uberclaw-helper spawn per child. A monitors.json entry tails the children's JSONL output and surfaces meaningful events back to the orchestrator. Conflict resolution always quotes the mission text; escalations are persisted as decision rows. State lives in flat JSON under ${CLAUDE_PLUGIN_DATA}/runs/<run-id>/. No daemon, no DB, no MCP server.

For the full design, see docs/UBERCLAW_PRD.md and orchestrator.md. Subagent contracts live in AGENTS.md. Project conventions (uv-only, atomic JSON writes, no second runtime, no-self-invocation) live in CLAUDE.md.

License

UberClaw v1 ships under the MIT license. Contributions: open an issue or PR on the repo.