Skip to content

Configuration

Pavel Erokhin edited this page Nov 20, 2026 · 4 revisions

Русская версия

ctxray works without a config: it then checks the five default harnesses with the mock model and built-in limits. A config tells it which harnesses you use, which model backend and gateway to reach, and which rules your organisation holds the context to. This page lists every key with its type, default, and the flag or environment variable that overrides it.

The config file

ctxray looks for one of these files in the folder it runs in, then in each parent folder up to the repository root, the folder that holds .git. So a command run from tests/ or app/ finds the project's config too:

File Format
ctxray.config.ts TypeScript: the default export is the config
ctxray.config.jsonc JSON with comments
ctxray.config.json JSON

Two of them in one folder is an error, not a silent pick. --config <file> points any command at another file. ctxray init writes a TypeScript config with Claude Code and Codex:

import { defineConfig } from "@mairwunnx/ctxray";

export default defineConfig({
  harnesses: {
    "claude-code": {},
    codex: {},
  },
});

defineConfig only gives the file its types. ctxray serves @mairwunnx/ctxray to the config itself, as it does for tests, so the file works without node_modules. A TypeScript config is code, so it can read environment variables or compute values. ctxray checks the result when it loads the file and names every key it rejects, with its path: ctxray.config.ts → policies[0].maxTokens.

A JSON config gets completion from the JSON Schema that each release publishes:

{
  "$schema": "https://github.com/MairwunNx/ctxray/releases/latest/download/config.schema.json",
  "harnesses": { "claude-code": {}, "codex": {} },
  "policies": [{ "id": "context-budget", "maxTokens": { "total": 25000 } }]
}

See the effective config

ctxray config prints the config a run works with: every extends merged, defaults filled in, and CTXRAY_* variables applied. The first line names the files that took part, the project's own last.

ctxray config
Config: ctxray.config.ts

{
  "harnesses": {
    "claude-code": {},
    "codex": {}
  },
  "backends": {},
  "offline": false,
  …
  "lang": "auto",
  "reportDir": ".ctxray/report"
}

The output goes through redaction first, your own redact.patterns included, so a proxy URL with a password in it shows without the password.

Keys

Every key is optional.

Key Type Default Overridden by
$schema string – –
extends string or string[] – –
harnesses { [id]: HarnessSettings or false } claude-code, codex, gemini-cli, opencode, cursor-cli --harness, CTXRAY_HARNESS
backends { [name]: "mock" or "replay" or "real" } {} –
upstream string (URL) the provider's own API CTXRAY_UPSTREAM
offline boolean false CTXRAY_OFFLINE=1
network object, below {} –
concurrency number 1 --concurrency, CTXRAY_CONCURRENCY
budget { usd?, tokens? } no limit --budget, CTXRAY_BUDGET_USD (dollars)
activate { min?, max?, runs? } min 0.8, max 0.2, runs 16 a test's own threshold or samples
exactTokens boolean false CTXRAY_EXACT_TOKENS=1
prices { [model]: Price } the built-in list –
ignoreHarnessDifferences boolean false --ignore-harness-differences, CTXRAY_IGNORE_HARNESS_DIFFERENCES=1
policies Policy[] [] –
redact { patterns?: (string or RegExp)[] } built-in patterns only –
limits object built-in limits –
lint { rules?, ignore?, errorOnWarnings?, overrides? } {} --error-on-warnings
reporters string[] console, or five reporters in CI --reporter, CTXRAY_REPORTER
lang "auto", "en", or "ru" auto --lang, CTXRAY_LANG
report.langs string[] the CLI language --report-lang, CTXRAY_REPORT_LANG
report.dir string .ctxray/report --report-dir

harnesses

The harnesses ctxray test runs on. A key with {} takes the defaults. Without the key, ctxray tests the five harnesses in the table above. Harnesses lists the ids and what each harness can do.

Setting Type Default Means
version string the recipe's tag The npm version range ctxray harness add pins, like 2.x
source "registry" or "system" registry system runs the harness found on your PATH instead of a pinned build
model string the harness's default model The model the harness runs with in L4–L7
provider string – The provider, for a harness that supports several. OpenCode takes anthropic or openai
userScope "isolated" or "inherit" isolated inherit copies your user-level rules, skills, and MCP servers into the run
experimental boolean false Turns on modes that rest on undocumented builds, like Cursor CLI's capture
concurrency number the run's concurrency At most this many sessions of this harness at once, under the run's limit

false instead of settings drops a harness an inherited config added:

export default defineConfig({
  extends: "@acme/ctxray-config",
  harnesses: { "gemini-cli": false },
});

backends

Who answers the harness in L6 and L7: mock, replay, or real, as Writing Tests explains. The config doesn't pick a backend for a run. --backend does, then CTXRAY_BACKEND, then mock. backends only gives backends names, so a CI job reads like its purpose:

export default defineConfig({
  backends: { pr: "replay", nightly: "real" },
});
ctxray test --backend pr

upstream, offline, network

upstream is the URL of your LLM gateway. Runs with the real backend, exact token counts, and ctxray gen-prompts go through it. Without it, ctxray talks to each provider's own API. offline: true forbids every network request: no harness installs, no --backend real, no exact counts, no ctxray gen-prompts, no ctxray calibrate. A command that needs the network stops with exit code 4 and says why, and counts fall back to local estimates. --backend replay and mock still work. A gateway inside your closed network needs no offline: name it in upstream.

network describes your corporate network:

Setting Type Means
proxy string HTTP(S) proxy URL. Overrides HTTPS_PROXY and HTTP_PROXY
noProxy string[] Hosts that skip the proxy. Overrides NO_PROXY
ca string[] PEM files with extra CA certificates, relative to the config file that names them. NODE_EXTRA_CA_CERTS adds one more
systemCa boolean Trust the system certificate store too. NODE_USE_SYSTEM_CA=1 does the same
registry string (URL) The npm registry harnesses install from. Overrides .npmrc and NPM_CONFIG_REGISTRY

Here the config wins over the environment: it's written for ctxray, and the variables are written for every program on the machine. Enterprise covers gateways, proxies, certificates, and closed networks.

budget and prices

A run with the real backend stops sending to the model once it reaches budget.usd dollars or budget.tokens tokens. Tests that start after that are skipped with “budget spent”. --budget <usd> and CTXRAY_BUDGET_USD set the dollars for one run.

ctxray knows the prices of the models its adapters run by default. prices adds others, or changes the known ones, in US dollars per million tokens:

export default defineConfig({
  prices: {
    "corp-sonnet": { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
  },
});

cacheRead and cacheWrite cost as much as input when you leave them out. A model nobody priced still runs, and the report shows its tokens without a cost.

concurrency

An L6 or L7 test launches its harness once per prompt and sample. By default ctxray runs these sessions one after another, so a small CI runner holds the run. concurrency lets several go side by side: the run gets faster and needs more memory, one session's worth per extra one (System requirements).

A harness's own concurrency caps it lower, for one that eats memory or trips its provider's rate limit:

export default defineConfig({
  concurrency: 4,
  harnesses: { opencode: { concurrency: 2 }, codex: {} }, // Codex runs 4 at once, OpenCode 2
});

--concurrency <count> and CTXRAY_CONCURRENCY set the run's limit for one run. L4 and L5 always run one session at a time.

activate

The defaults of L6 Activate for every test in the project. min is the share of runs a skill or rule must load in for toActivate(), 0.8 by default. max is the share it may load in at most for .not.toActivate(), 0.2 by default. runs is how many runs a test without samples gives each group of prompts.

Without runs, ctxray takes the fewest runs that can prove both thresholds: 16 for the defaults, 35 once min is 0.9. Fewer would leave even a model that never misses inconclusive. A threshold a test passes to toActivate({ … }), and the test's own samples, still win. Writing Tests explains the interval behind these numbers.

export default defineConfig({
  activate: { min: 0.9 }, // runs grows to 35 by itself
});

exactTokens

Local counts are estimates and show with ≈. exactTokens: true sends captured requests to the provider's count endpoint, through upstream and your key, so L4–L7 counts become exact. Harnesses explains which tokenizer each harness's estimate uses.

ignoreHarnessDifferences

L1 warns when the harnesses of a run get different instructions or skills: a rule only Claude Code reads leaves Codex without it. When you mean it that way, ignoreHarnessDifferences: true turns these harness-differences warnings off. lint.rules does the same per check, see Policies.

policies, limits, lint

policies holds your organisation's rules for the context, checked in L2 and L4. limits sets the size limits of skills, commands, and instruction files, and lint sets the level of each L1 check. Policies describes all three.

redact

ctxray hides API keys, tokens, emails, phone and card numbers before anything reaches disk. redact.patterns adds your own: a RegExp in a TypeScript config, its source as a string in JSON.

export default defineConfig({
  redact: { patterns: [/ACME-[0-9]{6}/] },
});

Reporters and Reports lists what redaction covers.

reporters and report

reporters picks the outputs of ctxray test: console, html, junit, allure, json, and markdown. Without it, a local run prints to the console. In CI it writes console, json, junit, markdown, and html. report.dir is where report files go, relative to the project root. report.langs lists the languages the HTML report carries, or all. Reporters and Reports describes each output.

lang

The language of the CLI: auto follows your system, en and ru pin one. Localization has the full order ctxray picks a language in.

extends

extends builds the config on top of others: a path, or an npm package resolved from the config file's folder. A list works too:

export default defineConfig({
  extends: ["@acme/ctxray-config", "./ctxray.ci.ts"],
  harnesses: { "claude-code": {}, codex: {} },
});

ctxray loads the configs depth first, so every config comes after the ones it extends. Later entries in the list win over earlier ones, and the file itself wins over all of them. Configs that extend each other in a loop are an error.

The configs merge by these rules:

What How it merges
Objects, like harnesses, network, budget, activate, limits, lint.rules Key by key
Arrays and plain values, like reporters or network.ca The later config replaces them
policies By id: a policy with an inherited id merges into it field by field, a new one goes to the end
redact.patterns They add up. A config can't drop the patterns it inherits
lint.ignore, lint.overrides They add up, the inherited ones first, so the project's own overrides win
A path in network.ca Stays relative to the config that names it

A policy must check something after the merge. One without maxTokens, denyMcp, requireMcp, and requireFiles stops the run. Enterprise shows a shared config published as a package, and Policies shows how a project adjusts an inherited policy.

Precedence

A flag beats a CTXRAY_* variable, which beats the config, which beats the default. CI sets variables per job, and the config file serves every job. Two kinds of setting work differently. offline, exactTokens, and ignoreHarnessDifferences turn on when either the variable or the config says so. And network beats the machine-wide proxy and certificate variables, as above.

Setting Flag Variable Config Default
Harnesses --harness CTXRAY_HARNESS harnesses five harnesses
Backend --backend CTXRAY_BACKEND names from backends mock
Layers --layer CTXRAY_LAYER – L1–L7
Upstream – CTXRAY_UPSTREAM upstream the provider's API
Sessions at once --concurrency CTXRAY_CONCURRENCY concurrency 1
Budget in dollars --budget CTXRAY_BUDGET_USD budget.usd none
Reporters --reporter CTXRAY_REPORTER reporters console, more in CI
Report languages --report-lang CTXRAY_REPORT_LANG report.langs the CLI language
Report folder --report-dir – report.dir .ctxray/report
CLI language --lang CTXRAY_LANG lang the system's
Warnings fail --error-on-warnings – lint.errorOnWarnings false

Environment variables

ctxray reads these variables. A switch counts as on when it's set to anything but an empty string, 0, or false.

Variable Means
CTXRAY_HARNESS Harnesses for ctxray test, comma-separated
CTXRAY_BACKEND mock, replay, real, or a name from backends
CTXRAY_LAYER Layers to run, like L1-L5, L3, or 3-5
CTXRAY_REPORTER Reporters, comma-separated
CTXRAY_REPORT_LANG Languages of the HTML report, comma-separated, or all
CTXRAY_LANG CLI language: en or ru
CTXRAY_UPSTREAM The LLM gateway URL. Overrides upstream
CTXRAY_UPSTREAM_KEY The key ctxray sends to the upstream, for every provider. It wins over the provider keys
CTXRAY_OFFLINE Switch: no network requests
CTXRAY_CONCURRENCY Harness sessions an L6 or L7 test runs at once
CTXRAY_BUDGET_USD Dollars a real run may spend
CTXRAY_EXACT_TOKENS Switch: count tokens with the provider's endpoint
CTXRAY_IGNORE_HARNESS_DIFFERENCES Switch: no warnings about harnesses getting different instructions
CTXRAY_CACHE_DIR The harness cache folder, see Harnesses
CTXRAY_CACHE_DIRS Layered caches, separated like PATH: the first writable one takes installs
CTXRAY_DEBUG Switch: a message missing from the chosen language says so

ctxray also reads the provider keys ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and CLAUDE_CODE_OAUTH_TOKEN, the network variables HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS, and NODE_USE_SYSTEM_CA, and the npm registry variables. Enterprise explains each. CI, GITLAB_CI, and GITHUB_ACTIONS make ctxray run as in CI, as CI Integration describes.

JSON Schemas

Each release attaches JSON Schemas for the files you write and the files ctxray writes. bun run schemas builds the same files into dist/schemas from the source.

Asset Describes
config.schema.json ctxray.config.json and .jsonc
tests.schema.json *.ctxray.jsonc declarative tests
lockfile.schema.json ctxray.lock
report.schema.json .ctxray/report/report.json
loadout.schema.json a Loadout snapshot
session.schema.json a captured session, turn by turn
inspection.schema.json ctxray inspect --json
exchange.schema.json one line of a trace file

They live at https://github.com/MairwunNx/ctxray/releases/latest/download/<name>.schema.json. Pin a version in the URL when your editor should follow a release you run rather than the newest one.

Clone this wiki locally