Skip to content

Capture Modes

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

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

ctxray learns what a harness loads in one of three ways. It reads the files, it launches the harness and records its requests, or it records a session you run yourself. Each way sees a different part of the Loadout and costs a different amount.

static reads your files and predicts the Loadout. capture launches the harness and records its requests. observe shows your own Claude Code session through ctxray’s plugin.

Which harness supports which mode

Harness static capture observe
Claude Code ✓ ✓ ✓
Codex ✓ ✓
Gemini CLI ✓ ✓
OpenCode ✓ ✓
Cursor CLI ✓ experimental

Cursor CLI capture runs through Cursor's undocumented local build, so you turn it on yourself:

export default defineConfig({
  harnesses: { "cursor-cli": { experimental: true } },
});

A test that needs capture skips a harness without it as unsupported, and the report names what's missing. Harnesses covers the files and launch details of each harness.

What each mode can see

static capture observe
Rules predicted from files what reached the model what reached the model
Skills listed, predicted listed and loaded listed and loaded
MCP servers by name from the config ✓ ✓
MCP tool schemas ✗ ✓, with deferred tools marked ✓, with deferred tools marked
System prompt and built-in tools ✗ ✓ ✓
Tokens local estimate of the files local estimate, or exact from the provider local estimate

Static mode is fast and free, but it only knows your files. It can't see the harness's own system prompt, its built-in tools, or the tools an MCP server offers, so their tokens are unknown, not zero. That's why inspect prints “after a run” for them. Capture fills the gap: its numbers are the real request.

static: reading files

ctxray emulates how each harness finds its files: which instruction files it reads in which folders, how imports and globs work, which skills and MCP servers it lists. It takes the project's files from git, including new files that aren't ignored, so it reads what a harness would see in your checkout. Nothing runs, and nothing leaves your machine.

capture: launching the harness

From L4 up, ctxray launches the real harness and records what it sends. It never does that in your working tree or with your real home folder:

ctxray copies the project, marks each file with a canary, and gives each session its own folder. The harness runs in a sandbox: its model requests go to ctxray’s proxy, MCP servers sit behind ctxray’s shim, and every other connection hits the egress guard. The redacted trace is cut into segments, which become the Loadout your test checks.

  • A copy of the project. ctxray copies the repository into a temporary folder with git clone --shared and lays your uncommitted changes over it, gitignored instruction files like CLAUDE.local.md included. Each session then gets its own copy-on-write clone of that copy.
  • Canaries. In the copy, ctxray appends a marker like ⟦ctx:CLAUDE.md⟧ to every instruction, skill, and command file. When the marker comes back in a request, ctxray knows that file reached the model, and its provenance says canary. Your own files never get one.
  • An isolated HOME. The harness runs with a fresh HOME, temp folder, and XDG folders inside the run. Your ~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, and ~/.cursor stay out of reach. On macOS a stub security command keeps the harness out of your keychain.
  • The model proxy. ctxray points the harness at a local proxy as its model provider, with a dummy key. The proxy answers with the backend you picked and records every exchange, redacted. MCP servers are routed through ctxray as well, so it hears each server's tools/list and counts every tool.
  • The egress guard. Every other connection goes to a proxy that refuses it and remembers the host. If the harness tries to reach anything past ctxray, the test fails and names the host.
  • The sandbox. On macOS, ctxray runs the harness under sandbox-exec, which forbids writes outside the run's folder. Codex sandboxes itself, and macOS refuses a sandbox inside a sandbox, so Codex runs without it. On other systems the CI container is the sandbox.

When a capture test fails, ctxray keeps the redacted trace of the session in a ctxray-traces-* folder in the system temp folder, so you can see what the harness sent.

Your own user-level setup: userScope

By default a launched harness sees nothing of your user-level setup, so every machine and CI get the same result. To check how your own rules, skills, and MCP servers combine with the project's, let them in:

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

With inherit, ctxray copies your user-level instructions, skills, agents, and commands into the run's home, never links them. Your MCP servers come along, routed through ctxray like the project's. Your settings files stay out, because they could point the harness past ctxray. Only Claude Code's hooks come in from its settings.json. Harnesses lists the folders each harness takes.

observe: the session you're in

/ctxray in ctxray's plugin for Claude Code shows what the session you're in loaded. It rebuilds the session's latest request from Claude Code's own transcript, with the system prompt, the tools, the rules and why each loaded, the skills, and the MCP servers, the way a capture cuts it. Nothing extra gets logged or installed for it. Claude Code Plugin shows it in use. The other harnesses keep too little of a session to rebuild it, so their observe column stays empty.

Why ctxray never touches your working tree

A test run has to give the same answer on your laptop and in CI, and it must leave no trace behind. So capture works on a copy, canaries go into the copy only, and the harness writes into a home folder ctxray throws away. Your real home stays out of it for a second reason: it holds your credentials and your personal setup, and neither belongs in a test result.

Clone this wiki locally