ocodex: cheap Muse Spark workers, paid supervisor

# ocodex

A parallel cheap-worker harness: Muse Spark 1.2 contributor workers fan out
on decomposable, cheap-to-verify work; one paid supervisor audits every claim,
prunes bad fixes, and finishes dead workers. Verification is cheaper than
generation — that is the whole product. OpenRouter is the fallback
(`ocodex-openrouter` / `OCODEX_PROVIDER=openrouter`).

Workers are fallible (stream disconnects, confident factual errors). They never
ship unsupervised. The launcher is capacity-aware, crash-checkpoints every
task, heartbeats every 2 minutes, retries empty/crash/stale-heartbeat once from the
checkpoint, and leaves a machine-readable ledger so the supervisor does not
burn tokens reconstructing what happened.

Power is **not** "spawn more workers". Default ceiling is **6** concurrent
workers. Muse contributor is 100 RPM / 3M TPM **per team**, so extra API keys
do not add slots. Scout effort is `low`, editors `medium` (interactive
`ocodex` stays profile `high`). Do not default to 20. One supervisor remains
the quality gate.

## Why a supervisor exists

First day in production (2026-08-25): 4 batches, 11 workers. About 25% died
mid-run on provider stream errors. One "successful" docs batch shipped 8
confident factual errors. The supervisor caught all 8 and finished 2 dead
workers' tasks. Net errors shipped: **zero**.

That is why the quality gate is a strong model reading diffs and running real
builds — not the worker's own "done" claim.

## Install

```bash
git clone https://github.com/fortun8te/ocodex && cd ocodex && ./install.sh
```

`./install.sh` is the whole setup path. It:

1. Copies `SKILL.md`, `SUPERVISOR.md`, `README.md`, and `scripts/` into
   `~/.claude/skills/ocodex` (and `~/.codex/skills/ocodex` when `~/.codex`
   exists).
2. Writes `examples/sample-manifest.json` with an absolute workdir.
3. Runs **doctor**: `ocodex` on PATH, optional `orslot`, Docker, SearXNG.

Re-run checks anytime:

```bash
python3 scripts/ocodex_managed.py doctor
```

### SearXNG (required for worker web search)

Someone else installing this **must** run SearXNG with Docker. Workers cannot
web-search without it. Doctor fails with the next command if it is down.

```bash
docker compose -f examples/searxng-compose.yml up -d
export SEARXNG_URL=http://127.0.0.1:8080   # default
python3 scripts/ocodex_managed.py doctor
```

Equivalent one-liner:

```bash
docker run --name searxng