Repository navigation
Capture Modes
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.
| 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.
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.
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.
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:
-
A copy of the project. ctxray copies the repository into a temporary folder with
git clone --sharedand lays your uncommitted changes over it, gitignored instruction files likeCLAUDE.local.mdincluded. 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 sayscanary. 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~/.cursorstay out of reach. On macOS a stubsecuritycommand 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/listand 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.
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.
/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.
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.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие