Claudexor

Claudexor

Claudexor is a local-first control plane for AI coding harnesses. It runs Codex CLI, Claude Code, Cursor CLI, OpenCode, raw API adapters, and future harnesses behind one typed interface.

The core rule is simple: a harness is not a role. Roles are intents such as explain, plan, spec, implement, create_from_scratch, repair, review, verify, synthesize, audit, and orchestrate. Any harness that declares the capability can be assigned the intent.

Current status: v2.0.0. See "Stability at 2.0" below for what is a stable contract and what remains experimental; retired verbs and mode ids hard-error with the new spelling instead of silently aliasing.

Prerequisites

• Node.js >= 20.19 (the daemon, CLI, and every surface run on Node)
• pnpm (via corepack: corepack enable pnpm)
• git (worktrees, envelopes, and delivery all use it)
• At least one logged-in vendor CLI — codex, claude, cursor-agent, or

opencode — OR a provider API key (adapters accept OPENAI_API_KEY, ANTHROPIC_API_KEY, ... as fallbacks; the raw-API route needs only a key)

• macOS for the desktop app; the CLI/daemon also run on Linux

Install

CLI + daemon from npm (installs the claudexor and claudexord bins):

npm install -g claudexor
claudexor doctor

You can also build from source — see Quickstart below.

The macOS app ships as a signed and notarized DMG on the Releases page — download, drag to Applications, open. The app is self-contained: it bundles its own daemon runtime and starts it on launch; installing the CLI is only needed for terminal use. (The v1.0.0 DMG was unsigned — if you kept it, either upgrade or approve it via System Settings → Privacy & Security → Open Anyway.)

Quickstart

pnpm install --frozen-lockfile
pnpm build

# Run the CLI from the repo (or add an alias/PATH entry for it):
node packages/cli/dist/cli.js doctor
alias claudexor="node $(pwd)/packages/cli/dist/cli.js"

claudexor ask "2+2?"
claudexor ask "google the latest release notes" --web auto
claudexor explore "map this repo's auth and run storage"
claudexor agent "fix the failing auth refresh test" --harness codex
claudexor best-of "fix add() and keep the patch minimal" --harness codex,claude --n 2
claudexor inspect 
claudexor follow      # live event tail of a daemon run; answers questions in the TTY
claudexor apply  --dry-run
claudexor doctor
claudexor secrets list
claudexor daemon start

apply --dry-run checks final/patch.diff with git apply --check and does not mutate the repo. Unknown flags and invalid --access/--web/--effort values fail loudly with exit code 2 — a typo never silently runs with defaults. When deterministic gates protect existing test/package surfaces and the task is explicitly test-authoring work, use --allow-protected-path to record typed per-run approval for those protected gate/test path changes. This does not bypass built-in critical/security human gates.

Modes

Canonical mode ids (exactly five intents; engine strategies are FLAGS, not modes):

• ask - read-only answer/explanation route. The macOS composer's no-project

fallback intent (Agent is the default on a project thread).

• plan - read-only multi-harness planning and draft SpecPack grounding.
• audit - read-only audit/map report; --swarm runs the bounded research

swarm (per-explorer findings, synthesis, omissions, follow-up questions).

• agent - default claudexor agent route. Strategy flags: --n N (best-of-N

race with isolated candidates, review, synthesis, arbitration), --attempts N (repair loop with a hard cap), --until-clean (repair loop until gates/review converge, budget/quota exhausts, cancellation happens, or the run stalls), --create (create-from-scratch intent).

• orchestrate - the orchestrator: routed like reviewers, produces a typed

orchestration plan over the six-tool vocabulary (startrun / race / status / answerquestion / apply / review); the default tool belt is five — answer_question is deliberately not offered by default. --autonomy suggest|auto_safe|auto_full controls how much the executor runs: suggest (default) plans only; auto_safe runs the safe steps (isolated envelope sub-runs / pure reads) and blocks at the risky apply step for a human decision; auto_full also applies through the single shared delivery gate, so it can mutate the live project.

Unknown modes fail loudly. The old strategy mode ids (best_of_n, max_attempts, until_clean, explore, create, readonly_audit) and the older ids (daily, until_convergence, readonly_swarm) are NOT aliases. Note the wire-mode vs CLI-verb distinction: claudexor explore and claudexor create are CLI convenience VERBS that map onto audit --swarm and agent --create, while the old WIRE mode ids above still hard-error at every API/DTO boundary.

Chat is the normal loop: claudexor with no arguments opens a REPL over a thread. Read-only turns (ask/plan/audit, and orchestrate with the default suggest autonomy) RESUME the routed harness's own native CLI session (codex exec resume, claude --resume) — plan first, then keep asking, in ONE conversation. Write (agent) turns run IN-PLACE: a single-candidate turn mutates the thread's live execution tree directly (the project for an in_place thread, or the thread's persistent git worktree for an isolated thread) and resumes the native vendor session, so the next turn sees the work. A race (--n N > 1) runs its candidates in isolated throwaway envelopes and AUTO-ADOPTS the winner's patch into the live tree. session.rebound is the typed disclosure for turns that CANNOT resume the native session in place — isolated-envelope candidates (race lanes included) and re-hosting onto a different harness; plain in-place turns resume natively with no rebound event.

Examples:

claudexor                       # REPL: a thread of turns (read-only turns resume natively)
claudexor ask "2+2?"
claudexor ask "google the latest release notes" --web auto
claudexor explore "map this repo's auth and run storage"   # = audit --swarm
claudexor agent "fix the failing auth refresh test" --harness codex
claudexor best-of "fix add() in src/math.js and keep the patch minimal" --harness codex,claude --n 2
claudexor agent "repair the parser test" --attempts 3
claudexor agent "fix the bug and keep repairing until clean" --until-clean
claudexor plan "design a config-to-gates implementation"
claudexor audit "map artifact writers and secret risk"
claudexor orchestrate "ship the v2 parser refactor across this repo"

Web, Tool Evidence, And Output Readiness

External web context is a typed run policy, separate from shell/network sandboxing. The CLI-first contract is:

claudexor ask "google this library's current release" --web auto
claudexor ask "use cached web context only" --web cached
claudexor ask "force live search where supported" --web live
claudexor ask "answer from local/project context only" --web off

The policy values are off | auto | cached | live. auto allows web-capable harness tools where supported and records whether the harness actually attempted WebSearch/WebFetch. A run that attempts a web tool and gets a tool error cannot be plain green success unless a later successful web result proves recovery. Read-only Ask/Audit can fall back to another eligible route and emits route.fallback.* events.

Run terminal state is separate from output readiness. Control API, CLI, and app expose outputReadyState (pending | finalizing | ready | diagnostic), webEvidence, tool errors, non-blocking tool warnings, budget, and artifact paths. A finished answer/report/patch can be usable with warnings; failed required web evidence, terminal harness errors, failed apply/verify steps, and failed required gates remain blockers. claudexor inspect is the CLI projection of the same run detail the macOS app renders.

Paid budgets are explicit: the API accepts {kind:"unlimited"} or {kind:"finite",maxUsd:N}; CLI --max-usd N maps to the finite form, and zero means a real zero-cash cap. Unknown cost is never reported as $0: a finite run can end cost_unverifiable, while a late exact charge above its cap ends exhausted_overshoot.

Deterministic gates use exact argv, never implicit shell parsing:

claudexor agent "fix the parser" --test '["pnpm","test"]'
claudexor trust --repo /path/to/project --grant-test '["pnpm","test"]'

The second command is required only for a test declared by versioned project config; the external grant is invalidated when the config, argv, executable, script bytes, project, or access profile changes.

Routing, Auth, And Secrets

Routing is Pool + Primary + Routing Goal:

• selected harnesses are the eligible pool;
• --primary-harness biases single-route modes and the first candidate;
• --routing-goal auto|quality|economy selects transparent pacing, exact

user-declared quality tiers, or minimum incremental paid spend. The nine v1 portfolio ids and --portfolio are hard errors.

Reviewer selection is also explicit when needed. --reviewer-panel accepts an ordered list of harness entries and preserves repeated harness ids, so one pass can request multiple Cursor models without provider-family dedupe:

claudexor agent "fix the parser" --reviewer-panel "claude=claude-opus-4-8:max,cursor=gemini-3.1-pro,cursor=gemini-3.5-flash,cursor=gpt-5.5-extra-high"

Each entry is harness[:effort] or harness[=model[:effort]]; a trailing :low|medium|high|xhigh|max suffix is parsed as effort, while other colons remain part of the model id when a model is present. Exact panels may intentionally contain several entries from the same provider, for example a Cursor-only diagnostics pass, but a clean verified review/apply gate still requires at least two distinct observed provider families. A same-provider-only panel can run and produce findings, but it remains ungated until another provider family participates. Legacy --reviewer-model and --reviewer-effort remain per-provider defaults for the automatic reviewer selector; an explicit panel is used verbatim and fails loudly if any requested harness is unknown, unavailable, disabled, fake-only, lacks review intent, or rejects an explicit model id that its adapter can enumerate. When an adapter has no enumerable model producer, the requested model must at least match the harness manifest's known-good model hints; otherwise the panel fails loudly instead of silently forwarding an unverifiable model to the native CLI. Use claudexor models --harness to inspect the current model ids for adapters that expose inventory.

In the chat surface this is sticky per thread: a thread remembers which harness answers in chat (its primary) and the eligible pool Best-of competes over. The macOS app sets them via POST /v2/threads / PATCH /v2/threads/:id and may override per turn — the engine still owns all routing; the surface only sends the choice.

Harness chips in the macOS app are not decorative toggles: unavailable, unauthenticated, degraded, or intent-incompatible harnesses are shown with the reason and are gated out of launch.

Claudexor mirrors native harness auth where that route is readiness-proven; API keys are fallback secret refs and live only in the v2-owned 0600 file store. auto is native-first for Codex, Claude, and Cursor in both host and scoped/envelope runs; it reaches an API-key fallback only when the native route is not ready (and, for Claude, no verified setup-token source is ready). A typed auth-route disclosure makes that paid-route switch visible. Run params, the daemon command journal, artifacts, summaries, patches, and PR text store only refs/metadata, not raw secret values. Subscription/native routes scrub provider API-key, token, and endpoint-override environment variables unless a distinct stored API-key or Claude setup-token route is selected. Doctor reports each produced auth source as two separate facts: credential availability (available | unavailable | unknown) and live verification (passed | failed | not_run). Explicit subscription never runs or accepts an API-key smoke, explicit api_key is never rescued by a native session, and auto remains native-first. A missing/logged-out source is unavailable + not_run; an indeterminate probe is unknown + not_run; source material that is present but wrong or unusable is available + failed.

Native login stays vendor-owned: Claudexor launches the official CLI with an absolute executable and structured argv, inherits its TTY, and removes provider key/token variables from the child environment. The native-login path never receives an OAuth callback, copies a credential file, or receives/stores vendor session tokens. Codex owns a Claudexor-dedicated CODEX_HOME and is forced to file credential storage there, so login cannot replace the operator's ordinary Codex CLI/app Keychain session. Claude owns its config plus the macOS login Keychain, and Cursor owns its Keychain-backed native state. Claudexor's separate API-key and Claude setup-token routes remain explicit local-secret-store flows. A zero vendor exit is only provisional; Claudexor then performs a fresh, source-targeted native probe and an isolated same-harness capability smoke. The smoke must answer an unpredictable challenge over the normal adapter stream from the exact vendor_native / native_session route, with no tools, external context, workspace mutation, or provider-key fallback. A timeout or crash is interrupted_unknown, never success and never auto-replayed. This proves the selected credential transport can answer; it does not prove a subscription tier, entitlement, quota, or zero incremental cost. The command routes follow the official Codex auth, Claude authentication, and Cursor CLI authentication documentation.

claudexor auth status
claudexor auth login codex    # codex login
claudexor auth login claude   # claude auth login --claudeai
claudexor auth login cursor   # cursor-agent login
claudexor secrets set openai --from-env OPENAI_API_KEY
claudexor secrets list
claudexor settings show
claudexor settings set routing_goal auto
claudexor settings set paid_fallback when_unavailable
claudexor quota --refresh --json

Managed secrets use the v2-owned 0600 file store. A disposable CLAUDEXOR_CONFIG_DIR therefore contains every managed-secret operation. The public CLI cannot select a storage backend.

auth status prints both typed readiness axes. Manifest auth sources say only what could be used; doctor source verification decides whether a route is actually ready.

Daemon And Control API

The managed daemon is the mandatory runtime authority and normally auto-starts when a product command needs it. It owns durable local command queueing over a Unix socket. A create is acknowledged only after its checksummed global-journal frame reaches fsync; Idempotency-Key binds retries to the original request. After a crash, an accepted nonterminal command becomes interrupted_unknown and is never auto-replayed. The loopback HTTP/SSE control API is a thin viewport over the daemon and run files. The canonical endpoint inventory lives in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) §7 and is generated from source; this README does not duplicate it.

GET /healthz is the sole unversioned route. Every product call uses /v2: official clients negotiate POST /v2/handshake, send X-Claudexor-Protocol-Major: 2, and can inspect the implemented contract at GET /v2/operations. Missing/incompatible negotiation returns a typed 426; there are no v1 aliases.

Harness setup is server-owned. /v2/setup/jobs (create / status

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: razzant
• Source: razzant/claudexor
• License: MIT

Install and usage instructions live in the source repository linked above.