Claudexor

Website

Claudexor is a local-first control plane for the AI coding agents you already pay for. It runs Codex CLI, Claude Code, Cursor CLI, OpenCode, Antigravity CLI, and raw API adapters behind one typed interface: a chat of turns where read-only questions resume the vendor's own native session, write turns land as inspectable patches, races pit harnesses against each other with cross-family review, and every claim — cost, quota, web evidence, auth route — is a typed fact you can audit, never a vibe.

Compared to driving a bare Codex or Claude Code session, Claudexor adds the layer the vendors do not ship: best-of-N races with independent reviewers and arbitration; honest budget/quota accounting (unknown cost is never $0); deterministic gates and protected paths; and — since 2.1 — credential profiles: named Antigravity/Claude/Codex/Cursor subscription bindings side by side, each with Claudexor-scoped state and platform-declared credential custody. Live subscription-quota tracking — and the opt-in policy that rotates a spent account out of the way on typed vendor limits — covers the harnesses with a vendor usage source (Antigravity, Claude, and Codex); Cursor has none yet. Everything runs on your machine, files are the source of truth, and there is no telemetry.

Current status: v3.10.2. 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.

Claudexor also runs as the exact-pinned delegated execution layer inside Ouroboros, a persistent self-developing agent. Ouroboros owns its tasks, memory, review, and final integration. Claudexor runs the connected coding harnesses and returns durable execution evidence. See Ouroboros in action.

Embedding callers can also make a single model request through a managed Codex subscription, using the same account as Agents. The caller supplies its own system prompt and tools and executes those tools itself. This is a typed engine operation, not a public OpenAI-compatible server or a second agent loop. Model catalogs and context limits are account-specific; subscription access does not guarantee zero incremental charges or enable provider-paid credits. See model operations for the transport, retention and unsupported-parameter contract.

Thanks to Praxis Relay and CLIProxyAPI for prior work exploring subscription-backed model transports. They informed this design; neither runs as an embedded relay or owns credentials in this integration.

If you use Claudexor — or you are an agent whose human does — a star is the one-click way to say it works.

• Prerequisites
• Install
• Remote SSH
• Quickstart
• Modes
• Credential Profiles And Quota
• Web, Budgets, And Gates
• Routing, Auth, And Secrets
• Daemon And Control API
• Artifact Layout
• Integrations
• Architecture
• Development
• Stability at 2.0
• For External Agents
• Privacy
• Uninstall / where your data lives

Prerequisites

• Node.js >= 20.19 (the daemon, CLI, and every surface run on Node)
• pnpm (via corepack: corepack enable pnpm)
• Git for isolated workspaces, candidate envelopes, and delivery. Supported in-place non-Git paths remain available; Doctor reports Git availability, and the app's Workspace Git check explains whether the selected shape is admitted.
• At least one logged-in vendor CLI — codex, claude, cursor-agent, opencode, or agy (Antigravity, for a Gemini subscription) — OR a provider API key (adapters accept OPENAI_API_KEY, ANTHROPIC_API_KEY, ... as fallbacks; the raw-API route needs only a key). Log in through Claudexor, not the bare vendor CLI — see Install And Login
• 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.

On a Mac, the app is the easiest way in — it ships as a signed and notarized DMG, so it installs like any ordinary Mac app, with no Gatekeeper warnings:

1. Download Claudexor-<version>.dmg from Releases.
2. Drag Claudexor.app into Applications.
3. Open it. The app starts its bundled Claudexor engine, then onboarding checks the external Git and harness route needed by the work you select.

The app bundles its own daemon runtime and starts it on launch; installing the Claudexor CLI is only needed for terminal use. Git and vendor harnesses remain separate capabilities checked before a run starts. (The v1.0.0 DMG was unsigned — if you kept it, either upgrade or approve it via System Settings → Privacy & Security → Open Anyway.)

Host integrations may install one vendor CLI into Claudexor's managed local toolchain with claudexor harness install <harness> --target local --yes --json; a host may bind that explicit unattended authorization to the user's Connect action. Exact npm pins install under ~/.claudexor/node; Cursor remains unpinned, so the JSON receipt records the downloaded installer's SHA-256 and byte length. Every successful executed receipt also records the absolute installed launcher and its verified version; a zero-exit installer without that postcondition is a typed failure. Omitting --target preserves the disclosed remote-host flow, its prefix and its exit-code contract; the install lease and the post-install proof are part of the unattended local contract and do not apply there.

Remote SSH

The macOS app can run a thread on a Linux or macOS SSH host while keeping the UI local. In Settings → Connections, pick a concrete alias from ~/.ssh/config or create one in-app — the form appends a plain Host block to ~/.ssh/config (after a timestamped backup), never a key or password. Connect it, then choose a saved folder or Browse on <host>… from the project picker. The thread is permanently bound to that host and folder; changing either creates a new draft.

Claudexor uses the system /usr/bin/ssh, so existing keys, ssh-agent, known_hosts, MFA and ProxyJump remain OpenSSH's responsibility. On first connection the app verifies and installs a signed, no-sudo runtime under ~/.claudexor/remote/, then reaches its loopback-only control API through an SSH local forward. Vendor CLIs and their credentials remain on the server and with the vendors. Claudexor can install a harness CLI on the host for you through a disclosed, exact-pinned flow — claudexor harness install, or Settings → Harnesses for a connected host: Claude, Codex, and OpenCode install one exact pinned npm version, while the Cursor and Antigravity vendor scripts are downloaded in full and run in the visible terminal where you watch them; nothing executes before the exact package/version/destination install recipe is disclosed and confirmed. An embedding host may instead pass --target local --yes, which installs into the managed toolchain root and must prove the launcher it installed before reporting success. (Installing them on the host yourself works too.) Then sign in from the app, which runs each vendor's own login in an embedded SSH terminal (Codex uses device auth). Remote threads include an embedded SSH terminal and an explicit-port preview tunnel.

Updates

v3.8.0, v3.9.0 and v3.9.7 release exceptions. These owner-authorized releases omit the three custom Ed25519 documents rather than publishing unsigned substitutes. Existing app installs therefore cannot take the in-place engine update to those versions, and the app cannot perform a first-time remote bootstrap from those releases. A fresh signed/notarized DMG, npm packages, and reviewed exact-pin embedders remain usable; normal releases keep the signed-manifest path below fail-closed (the client verifiers themselves stay fail-closed for the waived versions too).

• macOS app — each release publishes a claudexor-runtime-<version>.tar.gz closure (the bundled daemon and CLI, setup-login runner, Browser MCP, and native process-identity helper; Node, UI, and icons stay outside it) plus a signed runtime-manifest.json describing it. On foreground and from the bottom-left update chip / Check for Updates, the app reads that manifest and, if a newer runtime is offered, surfaces "Update available → vX.Y.Z". One click installs it in place, no new DMG: the app downloads the closure, verifies its SHA-256 against the signed manifest, unpacks it under ~/.claudexor/runtime/versions/<version>/, probe-starts it, waits until the engine is idle (it never interrupts running jobs), stops the daemon, swaps the active pointer atomically, relaunches, and re-checks the version — rolling back to the last-known-good runtime on any failure. The manifest is signed by a dedicated offline key the app pins; an unsigned, unknown-key, tampered, or downgraded manifest is refused. Node stays app-owned, so a Node bump still ships a new signed DMG. There is no background update timer; the check runs only when you open the app or click Check for Updates. The manifest's minAppVersion floor means an app that is too old is told to update the app itself rather than offered an incompatible engine.
• embedded hosts — the same signed manifest and the same Node-free closure may be exact-pinned by a host that owns its Claudexor daemon lifecycle. The archive contains only ordinary directories/files (internal package links are materialized), so its format needs no POSIX symlink support. The host supplies the exact full Node toolchain proven by its reviewed pin, launches claudexord.bundle.cjs, invokes operational commands through the adjacent claudexor.bundle.cjs, verifies --probe against the pinned {version,buildSha}, and uses --stop <observed-version> <observed-buildSha> before replacing a live closure. This is an extraction/daemon-bootstrap contract, not a claim that every harness or interactive login path has feature parity on Windows. The signed manifest is the upstream publication authority used to form that pin; a host may verify it live or rely on its reviewed exact URL/buildSha/SHA-256/size pin. minAppVersion remains the macOS app's compatibility field; embedders keep protocol, one tested Node toolchain, and separate daemon/CLI entrypoint bounds in their pin instead of creating a second Claudexor manifest or trust root. Start and stop must use the same CLAUDEXOR_CONFIG_DIR and, when overridden, CLAUDEXOR_DAEMON_SOCK, or the lifecycle command may address another daemon. A Windows consumer still owns a native extract/--probe/handshake/--stop smoke before claiming Windows support. The local harness installer is intentionally typed-unsupported on Windows in this release. On POSIX, npm-backed local installation additionally requires <node-root>/lib/node_modules/npm/bin/npm-cli.js; Claudexor never falls back to a npm found on ambient PATH.
• npm — CLI/daemon installs update the ordinary way: npm install -g claudexor@latest. claudexor release check reports whether a newer engine runtime is published, verifying the same signed manifest fail-closed (npm users update via npm).

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 ask --deep-scan "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 <run_id>
claudexor follow <run_id>     # live event tail of a daemon run; answers questions in the TTY
claudexor apply <run_id> --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 <glob[,glob...]> to record typed per-run approval for those protected gate/test path changes. This does not bypass built-in critical/security human gates.

Reviewers and approvals

Ordinary Agent runs skip internal model review by default, whether the executor is pinned or selected automatically. Completed changes remain normally applicable and show Not reviewed; required checks and patch-integrity checks still apply. Ask and Plan reject these Agent-only controls; Council is Plan's critique path:

• Review — --review enables automatic panel selection. Best-of and --until-clean include review. Explicit --attempts N keeps its review-based repair default; --no-review --attempts N repairs against configured checks and work completion without model reviewers.

• Reviewers — pick exactly who reviews a change. Pass --reviewer-panel a comma-separated list of unpinned harness=model:effort entries (model and effort are optional); repeat a harness to review through several models. For a deterministic account per slot, use the round-trippable --reviewer-panel-json '<array>' form with credentialProfileId. Example: --reviewer-panel-json '[{"harness":"claude","model":"claude-fable-5-1","credentialProfileId":"review-claude"}]'. An omitted profile uses the canonical account pool; a named profile is strict and never silently falls back. An explicit panel or reviewer model/effort override enables review without another flag. With --review and no panel, the engine chooses a cross-family panel and discloses families it skips.

• Approvals — mark paths that must clear a human before a change touching them can be applied. Set canonical repo-relative globs in the versioned .claudexor/config.yaml (empty by default):

  version: 1
  constraints:
    protected_paths:
      - migrations/**
      - "**/*.env"
  

  Creating, modifying, deleting, or renaming a matching path completes the run but pauses apply for a human decision. --allow-protected-path applies only to engine-derived gate/test paths and cannot suppress these project rules. Before a mutating turn starts, a live project thread with configured project protected paths is promoted one-way to its persistent isolated worktree. The run and patch therefore complete without touching the project tree; only the existing typed thread Apply decision can deliver the accumulated change. Direct one-shot --in-place agent runs refuse and name the isolation remedy.

Modes

Canonical mode ids (engine strategies are FLAGS, not modes):

• ask - read-only answer/explanation route. --deep-scan widens it into the bounded multi-scout research sweep with synthesis (per-scout findings, omissions, follow-up questions). Also the macOS composer's no-project fallback intent (Agent is the default on a project thread).
• plan - read-only planning; the plan lifecycle surfaces typed open questions and Implement freezes the plan as a content-hashed contract. Solo is the default; --council (optionally --n 2..4) drafts plans across N harnesses in parallel, then the primary merges them into ONE unified plan whose open questions reach you as a single set (see below).
• 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), --delegate (the delegation belt — see below).

Delegation (agent --delegate)

--delegate (agent-only) injects a SCOPED Claudexor MCP belt into the harness sandbox so the harness itself decides when to spawn bounded, isolated sub-runs (the industry pattern: Claude Code's Task tool, Cursor subagents, Codex spawn). The belt exposes only claudexor_ask / claudexor_plan / claudexor_run (isolated sub-run) / claudexor_best_of / claudexor_run_status / claudexor_run_result — there is NO apply/decision/thread/settings tool, so the PARENT integrates results in its own workspace. Policy is enforced server-side at the tool boundary: nesting depth is 1 (a sub-run cannot itself delegate), sub-runs are capped per parent (default 8), and each sub-run draws from the same live daemon-owned paid-budget authority as its parent. Reservations and settlements are enforced across the whole family; each child reports its own spend while the parent reports the aggregate. Only harnesses whose adapter declares capability_profile.mcp_injection (claude, codex, cursor) can host the belt. The flag is permission, not a requirement to create a child. Readiness and the final requested/effective/used outcome are engine-projected: a known pre-start incompatibility may continue as an ordinary Agent run only with a durable warning and typed remediation, while failure after belt injection is terminal on adapters with a startup receipt (claude, codex) — cursor hosting is pre-spawn injection with typed pre-spawn refusals, its live E2E and startup-status mapping gated as recorded in docs/FEATURES.md. Claudexor children carry a typed parent link; native vendor subagents never count as belt use. This replaces the former orchestrate mode (retired in v3): "suggest"-style planning is ordinary claudexor plan.

Council planning (plan --council)

--council (plan-only) runs the Council plan strategy: N harnesses each draft a plan in parallel (round 1, harness-native read-only planner transport, each in its own lane on a thread turn; Cursor uses native Ask so its final WorkReport remains available), the drafts land as file-backed run artifacts (council/draft-<harness>.md), and then an admitted member runs one merge iteration that points at the draft and attempt evidence files by absolute path (never embedding their full text) and synthesizes ONE unified plan. The tagged ## Open Questions parser runs on the MERGE output only, so you always answer a single question set — the downstream readiness/freeze/Implement flow is byte-for-byte identical to a solo plan. --n 2..4 sets the member count (default: distinct available harnesses, up to 3, primary first); --n on a plan is legal ONLY with --council. Degradation is honest: a failed member is disclosed (event + council/membership.yaml) and the merge proceeds with the usable inputs (one input still merges). A useful draft with a contradictory completed plus required_inputs report is retained as explicitly unverified input, while its original attempt remains failed. The merger prefers an accepted draft's lane, then an eligible unverified lane; no eligible input is a typed failure. The final plan must still pass its own checks. Run detail carries a council projection (membership + per-member status + who merged). Council is the plan critique path — the standalone "plan review" entity was retired in v3.

Unknown modes fail loudly. The retired mode ids (audit, best_of_n, max_attempts, until_clean, explore, create, readonly_audit, daily, until_convergence, readonly_swarm) are NOT aliases, and the retired audit/map/explore verbs hard-error pointing at claudexor ask --deep-scan. The retired orchestrate verb hard-errors pointing at claudexor agent --delegate. claudexor create remains a CLI convenience VERB mapping onto agent --create; old WIRE mode ids hard-error at every API/DTO boundary.

Chat is the normal loop: claudexor with no arguments opens a REPL over a thread. Read-only ask/plan turns RESUME the routed harness's own native CLI session (codex exec resume, claude --resume) — plan first, then keep asking, in ONE conversation. Each such turn runs in a DURABLE per-lane scoped home (a lane is a thread + harness + credential profile), so the native session it records survives the run and the next lane turn actually reaches it; a one-shot ask/plan with no thread keeps a disposable throwaway home. 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.

When a turn runs on a lane that has NOT seen the whole conversation — a lane switch (a different harness or account) or a gap (A→B→A) — the engine hydrates it with a bounded continuation packet: the delta turns since that lane's checkpoint, verbatim (past a byte budget the oldest turns are condensed — into a cached LLM summary when one is available, else mechanical one-liners), plus the active plan pointer and a workspace anchor. The packet is written as a file (context/THREAD.md in the run's artifact tree) and the prompt only points at its absolute path — the packet body never rides the prompt. Every hydrated turn DISCLOSES it (INV-137): a typed session.continuity event carries the stats, the turn record stamps a continuity field (native_resume | packet | fresh), and the CLI prints one line (e.g. continued with thread context · 3 turns). Returning to a previously used lane resumes i