# Claudexor > Local-first control plane for AI coding harnesses (Codex, Claude Code, Cursor, OpenCode): best-of-N runs, multi-model review, evidence-driven delivery - **Type:** MCP server - **Install:** `agentstack add mcp-razzant-claudexor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [razzant](https://agentstack.voostack.com/s/razzant) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [razzant](https://github.com/razzant) - **Source:** https://github.com/razzant/claudexor ## Install ```sh agentstack add mcp-razzant-claudexor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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): ```bash 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](https://github.com/razzant/claudexor/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 ```bash 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 (start_run / race / status / answer_question / 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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](https://developers.openai.com/codex/auth/), [Claude authentication](https://code.claude.com/docs/en/authentication), and [Cursor CLI authentication](https://docs.cursor.com/en/cli/reference/authentication) documentation. ```bash 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](https://github.com/razzant) - **Source:** [razzant/claudexor](https://github.com/razzant/claudexor) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-razzant-claudexor - Seller: https://agentstack.voostack.com/s/razzant - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.