ultracodex

Token-frugal orchestration for Claude Code. Claude acts as the architect: it breaks the task down, makes the design decisions, and verifies the critical results. The token-heavy work (writing code, searching, running tests) is delegated to a cheaper Codex worker via codex exec. Workers write to the filesystem rather than into Claude's context, so the expensive model never pays to re-read the code it delegated.

The result is the architect pattern: the strongest model directs, a cheaper model implements. Quality comes from a clear specification and from verifying the outputs that matter, not from the worker being the strongest available model, so the cheap lane can safely handle the mechanical majority of the work.

How it works

/ultracodex <task>
  Claude:  split into units, assign each a lane        (low token cost)
  Codex:   write / search / test, in parallel          (cheap lane, on disk)
           each replies in <=3 lines: status/files/tests
  Claude:  verify the critical results, synthesize     (low token cost)

Two rules keep the savings real:

1. Artifacts stay on disk; only summaries reach Claude. Claude reads a short status line per worker, never the full diff. Reading a worker's complete output back into context removes the benefit.
2. Escalate on stakes, not cost. Claude inspects the real artifact only when the work is security- or correctness-critical, a worker fails, or a summary looks wrong. Routine results are trusted from the summary.

Repository layout

File	Role
skill/SKILL.md	The routing doctrine Claude follows.
skill/codex-worker.sh	Runs one unit on Codex: resolves the binary, retries once, returns a summary, logs the run.
skill/codex-batch.sh	Fans many independent units out to Codex in parallel (single stage).
skill/codex-pipeline.sh	Runs each item through ordered stages (build → test → verify), per-item independent.
skill/resolve-codex.sh	Locates the Codex binary per-OS (Windows/macOS/Linux), newest non-obsolete build, validated before use.
skill/ucx-report.sh	Summarizes the worker + routing logs (runs, success rate, estimated tokens saved).
skill/ucx-doctor.sh	Preflight: checks the Codex binary resolves, runs, round-trips, and the hooks are wired.
skill/codex-review.sh	Optional cheap Codex first-pass review of a diff (via codex review); Claude still owns the verdict.
skill/ultracodex.config.toml	Codex profile for the worker (model, effort, sandbox).
skill/ultracodex.env	Persistent per-user worker defaults (model/effort/tier/…), sourced by the worker.
skill/ultracodex-config/	The /ultracodex-config skill — show/get/set/unset those defaults. Install as a sibling of ultracodex.
hooks/ultracodex-block-subagents.js	PreToolUse hook that enforces the routing.
hooks/ultracodex-session-notice.js	SessionStart hook that tells each session up front to use the skill.
skill/selftest.sh	Regression suite.
docs/DESIGN.md	Design and rationale.

Installation

Requires Claude Code and a working Codex CLI (codex exec).

cp -r skill ~/.claude/skills/ultracodex
# the config skill must be a SIBLING of the main skill, not nested inside it:
mv ~/.claude/skills/ultracodex/ultracodex-config ~/.claude/skills/ultracodex-config
cp hooks/ultracodex-block-subagents.js ~/.claude/hooks/
cp hooks/ultracodex-session-notice.js ~/.claude/hooks/
cp skill/ultracodex.config.toml ~/.codex/          # optional

Wire both hooks into ~/.claude/settings.json, merging with any existing hooks. The PreToolUse hook enforces the routing (denies implementation subagents); the SessionStart hook makes each session aware of the skill up front, so it routes correctly from the start instead of only after hitting a denial. The SessionStart hook self-gates — it emits nothing if the skill is not installed, so it is safe to leave wired everywhere.

"PreToolUse": [
  { "matcher": "Agent|Task|Workflow",
    "hooks": [ { "type": "command",
      "command": "node ~/.claude/hooks/ultracodex-block-subagents.js" } ] }
],
"SessionStart": [
  { "hooks": [ { "type": "command",
      "command": "node ~/.claude/hooks/ultracodex-session-notice.js" } ] }
]

The resolver targets the Codex binary bundled with the VS Code extension. Set CODEX_BIN if yours is installed elsewhere.

Usage

Run /ultracodex <task> on a substantial coding, refactor, or audit task. Individual workers can be tuned with environment variables, all optional and falling back to ~/.codex/config.toml:

Variable	Effect
ULTRACODEX_MODEL	Model for the unit: gpt-5.6-luna (bulk/cheap), gpt-5.6-terra (standard), gpt-5.6-sol (flagship, default).
ULTRACODEX_EFFORT	minimal, low, medium, high, xhigh, max, or ultra. Effort raises token volume, not rate; ultra spawns worker subagents (avoid — the skill fans out already).
ULTRACODEX_TIER	Service tier: priority (~1.5x speed, more usage) or default (Standard).
ULTRACODEX_SCHEMA	JSON Schema path for a structured {passed, summary} verdict.
ULTRACODEX_SEARCH=1	Allow the worker to use live web search.
ULTRACODEX_MCP	Comma-list of MCP servers for the unit (e.g. context7, playwright); default none.
ULTRACODEX_PROFILE	Layer a named Codex profile.
ULTRACODEX_NO_PREAMBLE=1	Skip the standing worker-instruction preamble.
ULTRACODEX_VERIFY	A fast compile/check command to run after the worker writes (e.g. tsc --noEmit, cargo check). Its result is appended to the summary; a failure does not mask the written files.
ULTRACODEX_EXPECT_FILES	Guard against a unit that exits cleanly having written nothing. 1 requires at least one file changed; a glob (e.g. out/*.md) requires a match. On a miss the run fails loudly instead of reporting a false success.
ULTRACODEX_SANDBOX	Codex sandbox mode (default workspace-write).
ULTRACODEX_TIMEOUT	Per-unit timeout (default 600s).

The hook is selective. Review and judgment subagents (reviewer, checker, verifier, auditor) continue to run on Claude, since the value of a review is that it is independent. All other subagent work is routed to Codex. Adjust with UCX_ALLOW_AGENTS and UCX_DENY_AGENTS, or disable enforcement with ALLOW_CLAUDE_SUBAGENTS=1 (or touch ~/.claude/.allow-subagents-<session_id>).

Notes and limitations

• A PreToolUse hook can deny a tool call but not reroute it. The block is enforced; the hand-off to Codex depends on the model reading the denial and acting on it.
• Codex performs well against a clear specification but is weaker at safety-critical judgment, which is why judgment and verification remain with Claude.
• Worker summaries are not always accurate. Trust the artifacts on disk and re-verify anything important.
• Developed on Windows with Git Bash. resolve-codex.sh detects the OS (Windows/macOS/ Linux) and also falls back to a codex on PATH; set CODEX_BIN if your binary lives elsewhere. The non-Windows layouts are inferred, not yet battle-tested — verify with bash skill/selftest.sh on first run.

Verifying the install

After installing (especially on a new machine), confirm Codex is actually reachable:

bash ~/.claude/skills/ultracodex/ucx-doctor.sh          # full preflight incl. a live round-trip
bash ~/.claude/skills/ultracodex/ucx-doctor.sh --quick  # skip the live call

It checks the binary resolves and runs, a trivial codex exec round-trips, and the hooks are wired — exit 0 means ready.

Testing

bash skill/selftest.sh                            # full suite, including live Codex runs
UCX_SELFTEST_NO_CODEX=1 bash skill/selftest.sh    # offline only

The suite covers binary resolution, the hook routing policy with its overrides and escape hatches, worker input validation, the $UCX_PYTHON fallback, and a live worker round-trip.

License and attribution

MIT licensed. Not affiliated with, endorsed by, or sponsored by OpenAI or Anthropic. "Codex", "Claude", and "Claude Code" are trademarks of their respective owners.