Repository navigation
Configuration
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.
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:
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 configConfig: 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.
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 |
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 },
});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 prupstream 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.
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.
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.
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
});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.
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 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.
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 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.
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 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.
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 |
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.
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.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие
{ "$schema": "https://github.com/MairwunNx/ctxray/releases/latest/download/config.schema.json", "harnesses": { "claude-code": {}, "codex": {} }, "policies": [{ "id": "context-budget", "maxTokens": { "total": 25000 } }] }