KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

claudexor

★ 414 Open GitHub ↗

Multi-harness control plane for Claude Code, Codex, Cursor, and OpenCode: quota-aware rotation across multiple Claude/Codex subscriptions, shared thread context, and cross-model review.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Claudexor

[![npm version](https://img.shields.io/npm/v/claudexor)](https://www.npmjs.com/package/claudexor)
[![npm downloads](https://img.shields.io/npm/d18m/claudexor?label=npm%20downloads)](https://www.npmjs.com/package/claudexor)
[![app downloads](https://img.shields.io/github/downloads/razzant/claudexor/total?label=app%20downloads)](https://github.com/razzant/claudexor/releases)
[![total downloads](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/razzant/claudexor/repo-metrics/docs/assets/downloads-badge.json)](https://github.com/razzant/claudexor/releases)
[![GitHub stars](https://img.shields.io/github/stars/razzant/claudexor)](https://github.com/razzant/claudexor/stargazers)
[![latest release](https://img.shields.io/github/v/release/razzant/claudexor?label=release)](https://github.com/razzant/claudexor/releases/latest)
[![license](https://img.shields.io/github/license/razzant/claudexor)](https://raw.githubusercontent.com/razzant/claudexor/main/LICENSE)

[Website](https://claudexor.ai/)

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, 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**: several Claude/Codex/Cursor subscriptions registered side by side,
each with its own isolated named login. 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 (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.4.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](https://github.com/razzant/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](https://ouroboros-agent.ai/).

If you use Claudexor — or you are an agent whose human does — a
[star](https://github.com/razzant/claudexor/stargazers) is the one-click way
to say it works.

![The Accounts and Quota surfaces: multi-account claude/codex/cursor list with
live usage, add & log in, auto-switch at quota limit, and per-window
5-hour/7-day quota bars](docs/assets/app-main-window.png)

![The thread workspace: threads sidebar, an agent turn with an inline artifact
preview and applied-change receipt, live per-account quota cards, and the
composer](docs/assets/app-agent-run.jpg)

- [Prerequisites](#prerequisites)
- [Install](#install)
- [Remote SSH](#remote-ssh)
- [Quickstart](#quickstart)
- [Modes](#modes)
- [Credential Profiles And Quota](#credential-profiles-and-quota)
- [Web, Budgets, And Gates](#web-budgets-and-gates)
- [Routing, Auth, And Secrets](#routing-auth-and-secrets)
- [Daemon And Control API](#daemon-and-control-api)
- [Artifact Layout](#artifact-layout)
- [Integrations](#integrations)
- [Architecture](#architecture)
- [Development](#development)
- [Stability at 2.0](#stability-at-20)
- [For External Agents](#for-external-agents)
- [Privacy](#privacy)
- [Uninstall / where your data lives](#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`, 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).
  Log in through Claudexor, not the bare vendor CLI — see
  [Install And Login](docs/AGENT_ONBOARDING.md#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):

```bash
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](https://github.com/razzant/claudexor/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.

![Installing the macOS app: the mounted DMG window with Claudexor.app being
dragged into the Applications folder](docs/assets/app-install-dmg.png)

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.)

## 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 &lt;host&gt;…** 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, and Cursor's vendor script is
downloaded in full and runs in the visible terminal where you watch it;
nothing executes before the exact command is disclosed and confirmed.
(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

- **macOS app** — each release publishes a `claudexor-runtime-<version>.tar.gz`
  closure (the bundled daemon, setup-login runner, Browser MCP, and native
  process-identity helper; Node, the CLI, 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 Node version proven by its reviewed pin, launches
  `claudexord.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 version, and 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.
- **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

```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 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

Two Agent-only power knobs shape review; Ask and Plan reject both, and Council
is the explicit multi-harness critique path for Plan:

- **Reviewers** — pick exactly who reviews a change. Pass `--reviewer-panel` a
  comma-separated list of `harness=model:effort` entries (model and effort are
  optional); repeat a harness to review through several models. Example:
  `--reviewer-panel "claude=claude-opus-4-8:max,cursor=gemini-3.1-pro"`. Omitted, the
  engine chooses a cross-family panel automatically.
- **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):

```yaml
  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) 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. 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 the PRIMARY runs one merge iteration that
POINTS at the draft 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 survivors (one survivor still merges — it normalizes the
format and extracts the questions); every member failing is a typed failure. 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 its native session and
injects ONLY the missed delta — never the whole conversation again.

The condensed prefix's summary is produced lazily at packet-build time: when a
collapse is forced and no fresh cached summary covers it, the engine runs ONE
bounded read-only pass (ask-mode, the lane's own harness + credential route, a
single turn, a hard timeout — no job queue) and caches the result keyed by
(thread, collapse-boundary turn) under the thread's lane dir. Later packets
reuse the cache until a new head turn advances the boundary; a timeout or an
unavailable harness falls back to the mechanical one-liners, so the packet
always carries the delta.

Inside the REPL, `/harness <id>` and `/profile <id|default>` set the thread's
sticky lane preference (its primary harness / credential profile) through the
same `PATCH /v2/threads/:id` route the app composer uses — a bare `/harness` or
`/profile default` clears it back to engine routing. Outside the REPL,
`--thread <id>` targets an existing thread so a one-shot `ask`/`plan`/`agent`
lands as its next turn (`--resume` picks the most recently updated thread); such
turns enqueue through `POST /v2/threads/:id/turns`, the one path that owns scope,
lineage, and the continuation packet.

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 ask --deep-scan "map this repo's auth and run storage"   # bounded multi-scout research sweep
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 ask --deep-scan "map artifact writers and secret risk"
claudexor agent --delegate "ship the v2 parser refactor across this repo"
```

## Credential Profiles And Quota

A credential profile is an ADDITIVE identity for one harness beyond its
default login: register several Claude or Codex subscriptions side by side,
each in its own isolated vendor config dir. Claudexor's default Claude and
Codex logins are also Claudexor-owned (`~/.claudexor/v3/native/...`);
ordinary `~/.claude` / `~/.codex` stores are never used or mutated. Profiles
may alternatively use namespaced secret-store keys
(`anthropic:work`, `openai:acc2`). Profiles are durable non-secret entries in
the global config's `credential_profiles`; secret material stays in the vendor
dir or the secret store.

```bash
claudexor profiles                         # symmetric accounts per harness: CLI login + named accounts
claudexor profiles add claude work         # register a config-dir login profile
claudexor profiles login claude work       # the vendor's own login, scoped to the profile dir
claudexor profiles disable claude work     # Enabled toggle: a disabled account is never routable
claudexor profiles enable claude work
# There is no "active account" to set. An unpinned run uses the harness's CLI
# login by default (or, with quota rotation enabled, the next ready enabled
# account); `claudexor profiles` shows the informational NEXT-UP identity that
# policy would pick (from readiness + quota). Enabled named accounts route only
# when you pin them — per-run --profile, or the composer's per-thread account chip.
claudexor settings set harness.claude.native_credentials_enabled false  # exclude the CLI login
claudexor secrets set claude_oauth:work --from-env TOKEN_VAR
claudexor agent "fix the parser" --profile work   # explicit per-run selection still wins
```

Accounts are **symmetric** (INV-135). Per harness, every account is a row with
an **Enabled** toggle — a disabled account is never routable. There is NO
user-settable "active" account. An unpinned run routes to the harness's CLI
login by default (or, when the opt-in quota rotation is on, the next ready
enabled account); `claudexor profiles` shows the informational **next-up**
identity that policy would pick (derived from readiness + quota) — not a claim
that every enabled account is a silent default. Enabled named accounts route
only through an explicit pin or that opt-in rotation. The native vendor login
is itself a symmetric row named **"CLI login"** with the same toggle semantics
but no Delete (the credential state is the vendor's, not Claudexor's — manage
it through `claudexor auth login <harness>`, which drives the vendor's own
login into the Claudexor-scoped store). Setting
`native_credentials_enabled: false` EXCLUDES the CLI login
from the ladder: a harness whose whole ladder is disabled then has nothing
routable and refuses loudly rather than silently falling back into it. The macOS
Accounts surface renders these rows directly from ONE server projection — no
client re-derives Enabled or next-up. Each row's secondary line shows the
account's non-secret **email · plan**, projected daemon-side from that account's
OWN Claudexor-owned store (never a vendor credential file the app reads itself,
and never the ordinary `~/.codex`/`~/.claude`). The per-thread PIN lives in the composer's
account chip: a thread remembers the account you explicitly choose there —
routing never silently creates a pin from an unpinned run; a run's
`--profile` overrides it. Selection is turn/thread pin `--profile` > POOL AUTO
(the enabled ladder led by the native/CLI login), and an explicit profile is
STRICT — exactly its transport or a typed refusal, never a silent fallback.
The engine-default API-key fallback is a credential route, not a synthetic
account: it adds no Accounts row and does not change the account count. When it
is the effective unprofiled route, the existing Next up/composer/footer
disclosure says **API key**; key management stays in Auth.
Vendor-session resume never crosses profiles. Subscription quota is tracked
per profile from the vendor's own `oauth/usage` endpoint (proactive
five-hour/seven-day/per-model percentages in the app's quota footer, one chip
per profile) — the access token is read transiently from the profile's own
vendor store, its macOS keychain item or on Linux the vendor's
`.credentials.json` in the profile's config dir — and each harness may declare
a typed `profile_policy`
(`limit_action: fail|ask|rotate`): rotation is opt-in and fires ONLY on typed
vendor-limit signals or a proactive headroom breach — never on ordinary
network errors — with full provenance on the run record. See
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) §5 for the complete contract.

## Web, Budgets, And Gates

External web context is a typed run policy (`--web off|auto|cached|live`),
separate from shell/network sandboxing. `off` is strict; `auto`, `cached`, and
`live` are optional preferences, so unused, denied, unavailable, or failed web
never blocks an otherwise useful result and remains visible as evidence or a
warning. A harness such as Cursor that cannot guarantee `off` is refused before
it starts, with a prompt to enable web or choose an enforceable harness. Run
terminal state remains separate from output readiness (`outputReadyState`).
Paid budgets are explicit (`--max-usd N`; zero is a real zero-cash cap) and
unknown cost is never reported as `$0` — a finite run can end
`cost_unverifiable` or `budget_overshoot`. Deterministic gates use exact
argv (`--test '["pnpm","test"]'`), and externally-granted test commands are
invalidated when the config, argv, executable, script bytes, project, or
access profile changes. The full semantics live in
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## Routing, Auth, And Secrets

Routing is `Pool + Primary + Routing Goal`: selected harnesses are the
eligible pool, `--primary-harness <id>` biases single-route modes, and
`--routing-goal auto|quality|economy` picks the pacing. In chat this is sticky
per thread. An explicit one-harness pool infers that harness as primary unless
`--primary-harness` is supplied; an explicit primary must belong to the pool.
The thread remembers its primary, pool, and (since 2.1) its
credential profile; the engine owns routing, surfaces only send the choice.
Reviewer panels are explicit when needed (`--reviewer-panel
"claude=claude-opus-4-8:max,cursor=gemini-3.5-flash"`); a clean verified
review/apply gate requires at least two distinct observed provider families.

Native harness auth is preferred where readiness-proven; API keys are fallback
secret refs in the v2-owned `0600` file store. `auto` is native-first, an
explicit route never falls back, and every effective route is a typed
disclosure — doctor reports credential `availability` and live `verification`
as separate facts, and a zero vendor exit is only provisional until a fresh
targeted probe plus an isolated capability smoke prove the exact selected
transport. Native login stays vendor-owned (official CLI, structured argv,
scrubbed env; Claudexor never sees or copies vendor tokens). The deep
semantics live in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) §5.

Codex login defaults to device-auth, driven in-app: the macOS AuthSheet shows
the one-time code and opens a private sign-in window (no Terminal); the CLI
prints the same code inline. Complete it in a window signed into no other
OpenAI account — an in-browser account switch can revoke sibling OpenAI
sessions server-side.
`claudexor auth login codex --browser-redirect` opts back into the older
localhost-callback flow. See
[Install And Login](docs/AGENT_ONBOARDING.md#install-and-login).

```bash
claudexor auth status
claudexor auth login codex    # codex login (device-auth by default)
claudexor auth login claude   # claude auth login (claude.ai subscription route)
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
```

## Daemon And Control API

The managed daemon is the mandatory runtime authority and normally auto-starts
when a product command needs it: durable fsync-acknowledged command queueing
over a Unix socket, idempotency-key retry binding, and a loopback HTTP/SSE
control API as a thin viewport (`/v2` only; `POST /v2/handshake` negotiation;
snapshot-then-subscribe run events). Harness setup/login is server-owned
through observable setup jobs with typed phases, deadlines, and post-exit
capability verification. The canonical endpoint inventory lives in
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) §7 and is generated from
source; this README does not duplicate it.

```bash
claudexor daemon start
claudexor daemon status --json
claudexor daemon logs
claudexor daemon stop
```

## Artifact Layout

Every project run creates files under the external per-project namespace
`~/.claudexor/v3/projects/<project-sha256>/runs/<run_id>/`; the repository's
`.claudexor/` directory remains user-owned versioned config. App-launched Ask
without a project uses an empty synthetic cwd at
`~/.cache/claudexor/no-project` and writes artifacts to
`~/.claudexor/v3/runs/<run_id>/`:

```text
events.jsonl
context/task.yaml
context/context_pack.yaml?
attempts/a01/attempt.yaml
attempts/a01/patch.diff
reviews/a01.yaml
arbitration/decision.yaml
final/run_facts.yaml
final/telemetry.yaml
final/patch.diff
final/work_product.yaml
final/summary.md
final/failure.yaml?
final/answer.md?
final/explore.md?
final/explore-findings.yaml?
final/omissions.md?
final/report.md?
final/plan.md?
context/context_error.md?
```

Files are the source of truth. Terminal output and UI rows are projections. The
macOS thread workspace surfaces Changes, Artifacts, and Evidence (with each
run's Outcome facts on top when a receipt is selected, and a remote-only
Terminal tab on remote threads) directly from these
artifacts/events, so successful answers and failed runs are inspectable instead
of disappearing into logs.

Standalone Agent runs use isolated envelopes by default, and Best-of candidates
always use isolated envelopes. They live under the same external project
namespace at `~/.claudexor/v3/projects/<project-sha256>/workspaces/.../tree`;
an isolated run's harness `cwd` is that envelope worktree. Chat thread turns
follow the workspace mode described above: `in_place` uses the live project,
while `isolated` uses its persistent thread worktree.

Proven work product means a git diff in the envelope, a declared run artifact,
or an explicitly verified host side-effect. Absolute `/tmp/...` writes are host
side effects and do not count as project success. A project prompt asking for a
tmp file should resolve to project-local `tmp/...` or a run artifact unless a
future verified host-side-effect mode is explicitly selected.

## Integrations

Claudexor can be driven by other tools through CLI JSON on supported commands, the
local daemon/control API, MCP, and ACP. These surfaces are capability-gated;
integrations should not assume every subcommand has JSON output or every
harness supports live steering (see "Stability at 2.0").

The CLI accepts repeatable/comma-separated `--attach <path>` or `--image <path>`
and immediately streams each regular, non-symlink file through `/v2/uploads`.
Finalize returns an immutable resource ID; run and turn requests accept only those
IDs, never local paths or base64. Every selected harness must declare a finite
MIME, byte/count limit, and native transport for every mandatory attachment or
preflight refuses the whole pool. Adapters verify the finalized digest immediately
before building the vendor payload.

Keep ONE `AGENTS.md` at your project root as the source of truth for
project-specific instructions. Claudexor bridges it to Claude Code automatically
(a thin generated `CLAUDE.md`, hand-written files never overwritten), so every
harness reads the same guidance. Full behavior in docs/INTEGRATIONS.md "Project
Instruction Files".

Host integrations are managed by `claudexor plugin
install|status|doctor|repair|uninstall <cursor|claude|codex|opencode|all>`.
They install user-global host-native artifacts plus MCP wiring while keeping
Claudexor as the orchestration owner. Codex is registered in the personal plugin
marketplace and still requires enablement from Codex Plugins. MCP tools are
one-shot final-output calls, not live Claudexor thread parity.

You can ask an agent host with shell access to install the integration for
itself. Paste something like this into Cursor, Claude Code, Codex, or OpenCode:

```text
Install Claudexor's host integration for this app. First find the local
Claudexor CLI: prefer an existing `claudexor` command; otherwise, if this repo
is checked out at <REPO_ROOT> (the directory containing this README), use
`node <REPO_ROOT>/packages/cli/dist/cli.js`.

Run the matching command for this host:
- Claude Code: `claudexor plugin install claude`
- Codex: `claudexor plugin install codex`
- Cursor: `claudexor plugin install cursor`
- OpenCode: `claudexor plugin install opencode`

Then run `claudexor plugin status <host>` and
`claudexor plugin doctor <host>`. Do not overwrite unowned files. If the
installer reports a conflict, show me the exact message and stop.

After install: Claude Code/OpenCode may need a new session; Cursor may need a
reload or manual local-plugin enablement; Codex is only registered in the
personal marketplace, so tell me to open Codex Plugins and enable Claudexor
manually.

Then follow the Install And Login sequence in docs/AGENT_ONBOARDING.md
(verify version/doctor, check plugin status before touching anything, and log
in only via `claudexor auth login <harness>` — never a bare vendor login).
```

GitHub Copilot uses the portable plugin in this repository rather than the
managed host installer:

```bash
npm install -g claudexor
copilot plugin install razzant/claudexor:plugins/copilot
```

The portable plugin supports macOS and Linux and requires the `claudexor`
command on `PATH`; Windows is not currently supported. It bundles one Agent
Skill plus MCP wiring and never collects credentials or bypasses Claudexor's
typed apply and human-decision gates. See
[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md#portable-agent-skill-and-copilot-plugin)
for lifecycle and precedence details.

The explicit Claude install also enables the official subscription-quota
status-line source. If `~/.claude/settings.json` already has a `statusLine`
command, Claudexor composes with it and restores it on uninstall; later user
drift is refused rather than overwritten. Only the documented five-hour and
seven-day usage/reset fields are retained in Claudexor's v2 data root.

Once enabled, ask the host to use Claudexor for work where orchestration,
review, or evidence is useful. Examples:

```text
Use Claudexor to make a read-only plan for this refactor, then show me the
plan and the open questions before changing files.
```

```text
Use Claudexor best-of with 3 candidates for this bug fix, compare the attempts,
and apply only the winning patch if the review is clean.
```

```text
Use Claudexor doctor/status to check which harnesses are actually ready before
choosing a route. Do not assume a provider is usable just because a token exists.
```

```text
Use Claudexor ask --deep-scan on this repository and return the final report with concrete
file references. Keep it read-only.
```

See [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) for the current integration
matrix and limitations.

## Architecture

Important boundaries:

- `packages/schema` owns contracts and generated JSON Schema.
- `packages/harness-*` adapters translate native tool I/O into typed events.
- `packages/workspace` owns worktree envelopes and scoped harness homes.
- `packages/orchestrator` owns the canonical mode pipelines (ask, plan, agent)
  and their separate schema-owned strategy controls; the canonical Modes
  section above defines them.
- `packages/review`, `arbitration`, `synthesis`, and `budget` own selection and
  validation logic.
- CLI, daemon, control API, MCP, ACP, plugins, and macOS are thin surfaces.

claudexor

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README