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

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:

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.

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:

docker run --name searxng