Skip to content

Concepts

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

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

A handful of ideas run through every command and test. Learn them once and the rest of the wiki reads faster.

The Loadout

Your project’s files go through the harness, which adds its own system prompt and tools, and the result is the model’s context: system prompt, built-in tools, rules, skills, MCP servers and tools, commands.

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.

Activation

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.

always loads in every session of its zone, path when the agent works with matching files, intent when the model picks it by description, manual only when you name it. The harness decides always and path, the model decides intent, and you decide manual.

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.

The harness

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.

Why one repository gives different harnesses different instructions

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.

Tokens

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.

Model backends

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 replay

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

Clone this wiki locally