Skip to content

Configuration ​

No config file is required. orcacompass setup, agents, prefer and ban write the common keys for you; the rest are edited by hand. Code: src/config.ts, src/paths.ts.

Where things live ​

PlatformConfigCache
Windows%APPDATA%\orcacompass\config.json%LOCALAPPDATA%\orcacompass\cache
macOS / Linux${XDG_CONFIG_HOME:-~/.config}/orcacompass/config.json${XDG_CACHE_HOME:-~/.cache}/orcacompass
ORCACOMPASS_HOME set$ORCACOMPASS_HOME/config.json$ORCACOMPASS_HOME/cache

Other tools' locations follow their own environment variables: ORCA_USER_DATA_PATH (Orca's data folder, for its agent switches and model catalog), CLAUDE_CONFIG_DIR (default ~/.claude, for Claude Code's model catalog), CODEX_HOME (default ~/.codex, for models_cache.json) and GROK_HOME (default ~/.grok, for models_cache.json and bin/).

A variable that is set but empty counts as unset. ~ is $HOME on macOS and Linux and %USERPROFILE% on Windows, the folder the agents themselves use.

The cache holds observed state only and is safe to delete:

FileContent
evidence-snapshot.json, evidence-check.jsonCached evidence and manifest check time
handouts.jsonRecent route hand-outs used to adjust pool usage
placements.jsonThe placement table: every model's tiers with the numbers behind them, built from every source; reused for placementsTtlHours
cursor-models.json, grok-models.json, antigravity-models.json, opencode-models.jsonLast good model listing per agent, used only when the live command fails
rejected-models.jsonModels agents refused at launch, written by verify

The four model-list caches use schemaVersion: 1, agent, fetchedAt (Unix milliseconds), and models: an array of { "id": "..." } objects with an optional provider label (Cursor keeps its labels, including NO ZDR). They store provider observations only. Computed tiers live in placements.json, which records the OrcaCompass version and the placement keys of the configuration (tierOverrides, costBands) in builtWith (schema 4), so a change to any of them rebuilds it. Recent hand-outs are stored temporarily; usage is read on each run. User preferences remain in config.json.

The listing commands run when the placement table is built, not on every route (Grok first checks its own native models_cache.json). A successful listing atomically replaces its JSON cache. If the command fails, a valid JSON cache is preferred; an old *-models.txt cache can still be read and converted to JSON, preserving its original timestamp and leaving the old file intact. Invalid JSON or unsupported schema versions are ignored. Sign-in failures never use a cached listing. Running cursor-agent models directly does not update OrcaCompass's cache; OrcaCompass writes it when it invokes that command during discovery.

How the file is read and written ​

  • A missing file means defaults. An unreadable or invalid file is exit code 2 with config error: <path>: <message>.
  • JSON objects deep-merge over the defaults; arrays replace them.
  • Unknown keys are ignored, silently, so a typo such as denyAgent has no effect and no warning. Unknown tier keys inside pins or defaultEffort are errors.
  • Known keys must have the documented types; numbers must be finite and non-negative. costBands must contain exactly three strictly ascending, non-negative numbers; invalid values are a config error naming the key.
  • classWeight is no longer used: it warns and is ignored, like scoreWeight and modelsDevTtlHours.
  • Commands that write the file change only their own keys. Every other key keeps its value and position, and the file keeps its indentation and line endings. The write replaces the file in one step, so a crash never leaves half a config. A file that is not a valid config is left untouched.

Keys and defaults ​

Which agents and models ​

KeyDefaultPurposeWritten by
allowAgentsomitted (all)Only these agents are eligibleagents only, agents enable (when the key exists)
denyAgents[]These agents are never used, even if allowedagents disable, agents enable
pins{}Preferred route per tier with optional model, e.g. { "daily": { "agent": "codex" } }. An eligible, unblocked favorite wins unless it exceeds preferRiskLimit and an unblocked alternative has known usage within the limitprefer
preferRiskLimit100Projected usage percentage above which a within-limit alternative replaces the favorite. Retain the favorite when no unblocked alternative has known usage within this limitprefer --risk-limit
banModels[]Model ids or families never routedban, unban
lastResortAgents["opencode"]Agents used only when no other agent can take the job in any allowed tier (or instead of waiting). --agent <id> or a preference for the tier lifts it; [] makes them ordinaryby hand
tierOverrides{}Model id or family to a tier: { "gemma4:12b": "light", "grok": "daily" }. Sets the cost tier only, leaving evidence bands and coverage unchanged; auto overrides are ignoredby hand
excludeNoZdrfalseExclude models marked no-ZDR (zero data retention). Relies on Cursor's NO ZDR labels onlyby hand
cursorAutotrueOffer Cursor auto as a fallback when no named model can be routedby hand

Usage ​

KeyDefaultPurpose
thresholds.longPercent95A weekly, monthly or bucket pool blocks its models at or above this usage
thresholds.sessionPercent90A session (5-hour) pool blocks at or above this; "hot" from 20 points below
usageRiskLimit90A route expected to end its usage window above this percentage is strained: it is used only when no other covering route is below the limit, in any cost tier. A higher value keeps routing in the cheapest cost tier for longer
usageStaleMinutes30Usage older than this caps confidence at medium; beyond 4x this, headroom becomes unknown and confidence low. Stale usage still blocks

Effort ​

KeyDefaultPurpose
defaultEffort{ "light": "low", "daily": "medium", "advanced": "medium", "frontier": "high" }Effort per requested tier when a route has neither --demand nor --effort
effortPolicy"balanced"How --demand maps to effort: efficient (low, low, medium, high), balanced (low, medium, high, high), quality (low, medium, high, xhigh) for low, moderate, high, exceptional. None maps to max

Efforts are none, minimal, low, medium, high, xhigh, max; the config requires the spelling xhigh.

Metadata and memory ​

KeyDefaultPurpose
costBands[1, 5, 12]USD per million blended tokens: Light below 1, Daily below 5, Advanced below 12, Frontier at or above 12; blend (3 × input + output) / 4
handoutMinutes10Lifetime of recent hand-outs
handoutPercent5Usage points added per hand-out per pool
evidenceTtlHours24Manifest check interval
placementsTtlHours5Placement cache lifetime; changed snapshot or placement settings rebuild it, and refresh forces a rebuild
rejectionTtlHours168How long a model an agent refused at launch (found by verify) is skipped

Example ​

config.example.json shows a typical setup rather than the defaults: it limits routing to Claude, Codex and Cursor (allowAgents), pins Claude Sonnet for Daily and adds one tier override (treating grok-4.7 as Advanced cost without changing its evidence). Its legacy classWeight is no longer used and warns; use costBands instead. Remove the agent restriction, pin and override to keep automatic selection; the other keys it lists are at their defaults, and keys it omits (effortPolicy, placementsTtlHours, rejectionTtlHours, lastResortAgents) keep theirs.

json
{
  "denyAgents": ["grok"],
  "pins": { "daily": { "agent": "codex" } },
  "preferRiskLimit": 120,
  "banModels": ["claude-haiku"],
  "tierOverrides": { "gemma4:12b": "light" },
  "effortPolicy": "quality"
}

This user never routes to Grok Build, prefers Codex for everyday jobs unless it is on pace for more than 120% of a window and a within-limit alternative is available, never uses a Haiku model, treats a local Gemma model as Light, and lets exceptional demand reach xhigh.

Data sources ​

Commands that gather a routing environment read usage and Orca's agent switches each time. Metadata and model listings are read when the placement table is built (see placementsTtlHours). tiers and refresh do not read usage. Setting a preference with prefer <tier> <agent> [model], listing or adding bans with ban, and removing bans with unban also gather that environment to check or display entries against discovered models. Agent selection edits, the bare prefer listing, prefer clear, prefer --risk-limit, and installer commands do not gather it.

SourceUsed forHow
orca account list --jsonUsage and limits per agentRun whenever the routing environment is gathered, 20 s timeout
Claude and Codex local catalogs, then the evidence snapshotModels and effort optionsRead at table build; fallback effort levels are assumed
Evidence snapshot and manifestCatalog and benchmark profilesCache, repository manifest and snapshot, then bundled fallback
cursor-agent modelsCursor model variants and NO ZDR labelsAt table build, 30 s, saved copy on failure
~/.grok/models_cache.json, then grok modelsGrok Build models, efforts, defaultAt table build: file, then live
agy modelsAntigravity models (id<TAB>label)At table build
opencode modelsOpenCode models (provider/model)At table build
Orca's profile state (profile-state.db or orca-data.json), read-onlyWhich agents you enabled in Orca (settings.disabledTuiAgents)Experimental; anything unexpected is unknown
orca orchestration worker-show / worker-readverify onlyRead-only

Privacy ​

OrcaCompass fetches the public evidence manifest and snapshot from this repository on GitHub without an API key. The optional --tier-reason is returned in command output and is not sent in these requests. Discovery reads machine metadata. Usage and configuration stay local. OrcaCompass collects no telemetry and calls no AI model. Background discovery commands run with stdin closed and bounded timeouts. Install, update and uninstall attach their interactive steps to your terminal. On Windows, OrcaCompass disables telemetry in the skills child processes to avoid their shutdown crash. The agent CLIs, npm, the Skill installer and Orca have their own network and privacy behavior. Diagnostics (status --json, agents --json) include local paths and usage details; sanitize them before sharing.