Repository navigation
Concepts
A handful of ideas run through every command and test. Learn them once and the rest of the wiki reads faster.
The Loadout is everything the agent went into a turn with: what the harness put into the model's context, piece by piece. ctxray inspect prints one, your tests check one, and ctxray diff compares two. Every Loadout holds:
| Part | What it is |
|---|---|
| System prompt | The harness's own instructions, split into sections. Only a launched harness shows it |
| Rules | Instruction files like CLAUDE.md, AGENTS.md, GEMINI.md, .claude/rules/*.md, .cursor/rules/*.mdc, each with its activation, reason, and tokens |
| Skills, listed | Skills the model sees by name and description, so it can ask for one |
| Skills, loaded | Skills whose whole body got into the context, because the model asked for them |
| MCP servers and tools | The servers configured for the harness, and each tool with its schema. A tool listed by name only, its schema held back until the model asks, is marked deferred |
| Commands | Slash commands the harness offers |
| Tokens | The total, the tokens by component (system, rules, skills, mcp, commands, tools), and the tokens of each MCP server |
| Provenance | For every chunk, the file it came from, why it loaded, and how ctxray tied the two |
Provenance answers “where did this come from?” for every chunk. Its evidence says how ctxray knows: static when it predicted the chunk from files, canary when a marker it planted in the file came back in the request, marker or fingerprint when it recognised the harness's own framing or the text itself. Capture Modes explains the canaries.
A Loadout also lists files that reach the model twice: sent again, or holding the same text as another file. Duplicates cost tokens and say nothing new.
A Loadout depends on where the agent starts and which files it works with. That's why inspect takes --cwd and --files, and why resolve() and assemble() in a test take the same.
Every rule and skill has one of four activation kinds. The same vocabulary covers every harness: Cursor's alwaysApply, globs, and description, Claude Code's paths, nested CLAUDE.md files, and the rest all map onto it.
Next to the kind, each rule carries the reason it loaded this time:
| Reason | Meaning |
|---|---|
cwd |
It sits in a folder on the way from the project root to where the agent starts |
always |
An unconditional rule, like a .claude/rules file without paths
|
nested:<file> |
The agent works with <file>, and the rule sits in a folder between the start folder and that file |
glob:<glob> |
A file the agent works with matches the rule's <glob>
|
import:<path> |
The file at <path> imports it, like @AGENTS.md in a CLAUDE.md. It inherits that file's activation |
description |
A Cursor rule the model may pick by its description |
config |
The harness config names it, like the instructions of opencode.json
|
When ctxray launches a harness and finds a rule in the request it didn't predict, the rule's reason is observed.
Not every harness supports every kind. Codex has no path rules: it reads its AGENTS.md files once, from the root to the start folder, and the files the agent touches change nothing. Harnesses lists what each harness reads and how.
A harness is the program that wraps the model: Claude Code, Codex, Cursor CLI, Gemini CLI, OpenCode. It finds your instruction files, lists your skills, starts your MCP servers, writes a system prompt of its own, and sends all of that to the model. ctxray knows five of them:
| Id | Harness |
|---|---|
claude-code |
Claude Code |
codex |
Codex |
cursor-cli |
Cursor CLI |
gemini-cli |
Gemini CLI |
opencode |
OpenCode |
Without a harnesses key in the config, ctxray tests all five.
Each harness reads its own files. Claude Code reads CLAUDE.md and .claude/rules. Codex reads AGENTS.md. Gemini CLI reads GEMINI.md, or the names its settings give. A rule you wrote in .claude/rules/payments.md never reaches Codex, and a teammate who works in Codex never sees it.
ctxray catches this at L1 with the harness-differences warning. For every file one harness reads and another doesn't, it checks whether the other harness still gets the same text: through a copy, a symlink, an import, or the same words in a file it does read. When it doesn't, you see:
⚠ .claude/rules/payments.md Codex doesn't read this file, and nothing it reads says the same, so the harnesses get different instructions. Only Claude Code reads it harness-differences
The usual fix is to keep shared rules in AGENTS.md and import it from CLAUDE.md with @AGENTS.md. When the difference is on purpose, turn the warning off with --ignore-harness-differences, the config key ignoreHarnessDifferences: true, or CTXRAY_IGNORE_HARNESS_DIFFERENCES=1.
Commands and subagents belong to each harness, so they never count as a difference. Two related checks look at files no harness of the run reads. When only a harness outside the run reads it, you get the other-harness warning. When no harness reads it and nothing links to it, you get unread, an error: the file is written for agents, and none of them ever sees it.
Every Loadout says how many tokens each piece costs, and how it counted them. A count made on your machine is an estimate. ctxray always marks it with ≈ and never shows it as exact, in the terminal, the HTML report, or the Markdown summary.
The tokenizer depends on the harness and the model family behind it:
| Harness | How ctxray counts | Method in the output |
|---|---|---|
| Claude Code | o200k, scaled by factors measured against Claude's own count, per kind of text: prose, code, JSON, non-Latin text, metadata | local:o200k_base+calibrated:claude-sonnet-5-5 |
| Gemini CLI | the Gemma vocabulary, which ctxray carries inside. o200k if it can't load | local:gemma4 |
| Codex, OpenCode, Cursor | o200k, the tokenizer of OpenAI's current models | local:o200k_base |
Claude's factors sit between about 1.54 and 1.68: Claude counts more tokens than o200k for the same text. ctxray calibrate measures them again with your key, see Commands.
For exact numbers, let the provider count. Set exactTokens: true in the config or CTXRAY_EXACT_TOKENS=1, and every captured Loadout is counted by the provider's own endpoint, through your upstream and your key:
| Provider | Endpoint | Method in the output |
|---|---|---|
| Anthropic | /v1/messages/count_tokens |
provider:anthropic.count_tokens |
| OpenAI | /v1/responses/input_tokens |
provider:openai.input_tokens |
| Gemini | /v1beta/models/<model>:countTokens |
provider:gemini.countTokens |
Exact counts lose the ≈ and add framing: the tokens no component owns, like the conversation and the tool-use preamble. ctxray caches them in tokens.db in its cache folder, so the same text is never counted twice. Chat Completions has no count endpoint, so Cursor CLI and OpenCode's default provider stay estimates. An offline run never asks for exact counts. Configuration and Enterprise cover the upstream and the keys.
Reading files can't tell what the system prompt, the built-in tools, or the MCP tool schemas cost. inspect shows them as “after a run”: ctxray counts them once it launches the harness, from L4 up.
Tests from L4 up launch the real harness, and the harness talks to a model. ctxray stands between them and decides who answers:
| Backend | Who answers | Cost |
|---|---|---|
mock |
Your test says what the model answers, turn by turn. A resent turn gets the same answer | free, deterministic |
replay |
Answers recorded earlier, played back from __cassettes__/ next to the test file |
free, deterministic |
real |
The real model, through your provider or gateway and your key | what the provider charges |
mock is the default. L4 and L5 always run against it, whatever backend you pick: they check what the harness sends, not what the model says. L6 and L7 need a model that answers by itself, so on mock they're skipped. Run them with --backend real --record once to keep the answers, then --backend replay on every merge request for free.
ctxray test --backend real --record --budget 2
ctxray test --backend replayYou can name backends in the config, like backends: { pr: "replay" }, and pick one with --backend pr or CTXRAY_BACKEND. Writing Tests shows cassettes and budgets, and CI Integration where each backend fits.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие