Skip to content

Harnesses

Pavel Erokhin edited this page Nov 21, 2026 · 9 revisions

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

A harness is the program that wraps a model into an agent: Claude Code, Codex, Gemini CLI, OpenCode, Cursor. Each one reads its own files, in its own order, with its own quirks. This page says what ctxray knows about each of them, how it launches them, and how it pins their versions so your CI tests the same builds as you.

Support matrix

ctxray knows five harness ids. There are no others: an unknown id fails with “Unknown harness”, and you can't register your own.

L1 to L3 work for every harness. L4 to L7 launch the harness, so they work for Claude Code, Codex, Gemini CLI, and OpenCode, and for Cursor CLI as an experiment.

id Title Modes Capabilities Default model Token counter
claude-code Claude Code static, capture, observe skills, pathRules, mcp, hooks, headless, proxyable claude-sonnet-5-5 o200k scaled by measured Claude factors: local:o200k_base+calibrated:claude-sonnet-5-5
codex Codex static, capture skills, mcp, hooks, headless, proxyable gpt-5.5 local:o200k_base
gemini-cli Gemini CLI static, capture skills, pathRules, mcp, hooks, headless, proxyable gemini-2.5-flash Gemma vocabulary, local:gemma4, o200k if it can't load
opencode OpenCode static, capture skills, pathRules, mcp, hooks, headless, proxyable claude-sonnet-5-5 local:o200k_base
cursor-cli Cursor CLI static, capture (experimental) skills, pathRules, intentRules, mcp, hooks, headless claude-sonnet-5-5 local:o200k_base

The modes are explained on Capture Modes. In short, static reads files, capture launches the harness against ctxray's proxy, and observe shows the Claude Code session you're in, through ctxray's plugin.

A test can list the capabilities it requires (see Writing Tests). A harness that lacks one reports the test as skipped: unsupported instead of failing it:

Capability Means
skills skills are listed by description and loaded on demand
pathRules rules or nested context files load when the agent works with matching files
intentRules rules (not skills) the model picks by their description
mcp MCP servers and their tools
hooks lifecycle hooks ctxray can observe through
headless runs without a UI, so ctxray can launch it
proxyable sends its model requests to a base URL ctxray sets

Every token count made on your machine is an estimate and shows with ≈. Exact counts need the provider's count endpoint, see Configuration (exactTokens).

How ctxray reads a project

All harnesses share a few rules, so the sections below don't repeat them.

  • Which files exist. ctxray asks git: git ls-files --cached --others --exclude-standard, minus deleted files. So a file your .gitignore hides doesn't count, the way it wouldn't reach a teammate. Outside git, ctxray walks the folder and skips .git/ and node_modules/. Either way it leaves out its own folders at the project root, .ctxray/ and .ctxray-cache/: no harness reads them.
  • The chain. The folders from the project root down to the folder the agent starts in (--cwd) form the chain. Files in the chain usually load at launch.
  • Below the start folder. When the agent works with a file deeper down (--files), the folders between the start folder and that file can add their own context files.
  • Activation. Every rule says why it loaded: always (in every session of its folder), path (when the agent works with a matching file), intent (the model picks it by description), or manual (only when you name it). The reason next to it is one of cwd, always, nested:<file>, glob:<glob>, import:<path>, description, config.
  • What static mode can't know. The system prompt, built-in tools, and MCP tool schemas live inside the harness. ctxray inspect lists MCP servers by name and shows “after a run” for the rest. A capture fills them in.

Which files each harness reads

Every harness reads its own list of files. The sections below give the order and the details.

A table of instruction, rule, skill, and MCP files, and which of Claude Code, Codex, Gemini CLI, OpenCode, and Cursor reads each.

Claude Code

ctxray emulates Claude Code 2.1.

Files and order. Claude Code reads CLAUDE.md, CLAUDE.local.md, and the rules in .claude/rules/**/*.md. In each folder of the chain the order is CLAUDE.md, then the rules without paths, then CLAUDE.local.md. A CLAUDE.md inside .claude/ belongs to the folder that holds .claude/. ctxray looks for CLAUDE.local.md in every folder, even when git ignores it, because that's what the file is for. A file over 4 MiB is an error.

AGENTS.md only without CLAUDE.md. Claude Code reads AGENTS.md only when no CLAUDE.md sits anywhere in the chain, and in a folder only if that folder has no CLAUDE.md or CLAUDE.local.md. An AGENTS.md that a CLAUDE.md shadows, and that nothing imports, lands in the ignored list. Import it from CLAUDE.md with @AGENTS.md if you want both.

Imports, four hops deep. @path pulls in a file relative to the importing one, and an imported file can import further, up to 4 hops. Paths that start with ~ or /, or leave the project, stay out. Imports expand only in files at the start folder or below it: a CLAUDE.md above the start folder loads without its imports. ctxray checked that on Claude Code 2.1.311.

Activation.

  • Files in the chain load always, reason cwd.
  • A folder below the start folder that holds a file the agent works with adds its files as path, reason nested:<file>.
  • A rule with paths: in its frontmatter loads as path, reason glob:<glob>, when a working file matches. The globs are relative to the rule's folder.
  • Claude Code reads only paths in a rule's frontmatter. Any other field, such as Cursor's globs, gets the warning lint.ruleField.

Skills. .claude/skills/<folder>/SKILL.md, in any folder the agent can reach. The skill's name is its folder: a different name in the frontmatter gets a warning. The description is description (or the first line of the body) plus when_to_use, cut at 1536 characters. disable-model-invocation: true keeps the skill out of the listing. paths: lists it only when a working file matches. Claude Code looks exactly one folder down: .claude/skills/payments/refunds/SKILL.md never loads. A tab in the frontmatter makes it skip the skill.

Commands. .claude/commands/**/<name>.md. A skill with the same name wins over the command.

MCP. mcpServers in .mcp.json. Each server needs command or url. disabledMcpjsonServers in .claude/settings.json or .claude/settings.local.json turns servers off.

Capture. ctxray runs:

claude -p <prompt> --output-format stream-json --verbose --model <model> --permission-mode bypassPermissions

with CLAUDE_CONFIG_DIR in the run's own home, ANTHROPIC_BASE_URL pointing at ctxray's proxy, a dummy ANTHROPIC_API_KEY, and telemetry, error reporting, the auto-updater, and non-essential traffic turned off. As root, Claude Code refuses bypassPermissions, so ctxray sets IS_SANDBOX=1 only then. The project's .mcp.json in the copy is rewritten so every server runs behind ctxray.

Install recipe. npm package @anthropic-ai/claude-code, dist-tag stable by default. The native build comes from @anthropic-ai/claude-code-<os>-<arch>[-musl]@<version>, executable claude (claude.exe on Windows).

Codex

ctxray emulates Codex 0.169.

Files and order. In each folder of the chain Codex takes the first non-empty file of AGENTS.override.md, AGENTS.md, and then the names in project_doc_fallback_filenames from .codex/config.toml. The others in that folder are shadowed, and an empty file gets a warning.

No path rules. Codex fixes the chain from the root to the start folder when the session starts. Reading a file deeper down loads nothing, so every Codex rule is always, reason cwd. A test that requires pathRules skips on Codex.

The 32 KiB budget. Codex stops at project_doc_max_bytes, 32 KiB (32768 bytes) by default. The file that crosses the limit is cut, and the files after it are dropped. ctxray warns about both, so you see which instructions never reach the model.

Skills. .agents/skills/<folder>/SKILL.md in the chain, from the start folder up to the root, plus .codex/skills/<folder>/SKILL.md at the root, in subfolders too, like .agents/skills/payments/refunds/SKILL.md. Both name and description are required, and a skill without them is an error. Codex also skips a SKILL.md that starts with a byte order mark or has a tab in its frontmatter. A [[skills.config]] entry with enabled = false turns a skill off, matched by name or by absolute path. The last match wins.

Commands. Codex has no project commands.

MCP. [mcp_servers.<name>] in .codex/config.toml. enabled = false turns a server off. Broken TOML is reported.

Capture. ctxray runs:

codex exec --json -s read-only -m <model> --skip-git-repo-check <prompt>

with CODEX_HOME in the run's home. ctxray writes a config.toml there with its own model provider (base_url pointing at the proxy, the Responses wire API, no retries), with analytics, feedback, history, and update checks off, and with the copy marked as trusted. MCP servers go behind ctxray through -c mcp_servers.<name>.… overrides. A server whose name holds a dot can't be overridden this way. Codex sandboxes itself, and macOS refuses a sandbox inside a sandbox, so ctxray runs Codex without its own.

Install recipe. npm package @openai/codex, dist-tag latest. Each build is a prerelease of the same package, @openai/codex@<version>-<os>-<arch>. The Linux builds are static musl executables, so glibc and musl machines share them.

Gemini CLI

ctxray emulates Gemini CLI 0.68.

Files and order. Gemini CLI reads GEMINI.md, plus the names context.fileName adds in .gemini/settings.json (one string or a list). A file named AGENTS.md counts as such. Context files from the root to the start folder load always, sorted by path. When the agent touches a file deeper down, the context files between the start folder and that file join as path, reason nested:<file>. Empty files are skipped with a warning.

Imports. @path imports go up to 5 hops. An imported file inherits the activation of the file that imports it, reason import:<path>.

Settings only from the start folder. Gemini CLI reads .gemini/settings.json only in the folder it starts in. The same goes for skills and commands: only the start folder's own .gemini/ and .agents/ count. A .gemini/settings.json in a parent or child folder matters only for a session that starts there, so test each start folder you use with --cwd.

Skills. .gemini/skills/<folder>/SKILL.md and .agents/skills/<folder>/SKILL.md. Gemini CLI looks exactly one folder down. name and the description key are required: Gemini CLI silently drops a skill without them, and ctxray warns. An empty description: still lists the skill, with nothing to pick it by. In name, the characters : \ / < > * ? " | become -.

Commands. .gemini/commands/**/*.toml, with prompt and description. git/commit.toml becomes /git:commit. Gemini CLI expands commands itself and never lists them to the model.

MCP. mcpServers in the start folder's .gemini/settings.json, with transport command, url, or httpUrl. mcp.allowed keeps only the servers it names, and mcp.excluded drops servers.

Capture. ctxray runs:

gemini -p <prompt> -m <model> -o stream-json --approval-mode yolo

A build from ctxray's cache is bundle/gemini.js, so ctxray runs it with node. yolo makes Gemini CLI show the model every tool. GOOGLE_GEMINI_BASE_URL points at the proxy, GEMINI_CLI_HOME at the run's home, and the system settings paths at files that don't exist, so your machine's settings stay out. A settings file in the run's home picks API key auth and turns usage statistics, telemetry, and auto-update off. Gemini CLI needs node on PATH: without it the capture fails, and ctxray doctor reports it.

Install recipe. npm package @google/gemini-cli, dist-tag latest. It's one bundle for every platform, bundle/gemini.js, run by Node.

OpenCode

ctxray emulates OpenCode 1.19.

First name wins. OpenCode knows three context names, in this order: AGENTS.md, CLAUDE.md, CONTEXT.md. At launch it picks the first name that exists anywhere between the start folder and the root, and then loads every file of that name on the way, always, reason cwd. A lower-priority file beside a higher-priority one never loads. So one AGENTS.md deep in the tree is enough to make every CLAUDE.md above it invisible.

Configured instructions. instructions in opencode.json, opencode.jsonc, or .opencode/opencode.json(c) along the chain adds files by path or glob, always, reason config. URLs, ~/ paths, and absolute paths stay out.

Below the start folder. Each folder between the start folder and a touched file adds its first context file, as path.

Skills. .opencode/skill/, .opencode/skills/, .claude/skills/, and .agents/skills/, each as <folder>/SKILL.md, in subfolders too, from the start folder up to the root. A deeper skill hides a skill of the same name above it. name and a description string are required: description: "" passes, a bare description: doesn't.

Commands. .opencode/command/ or .opencode/commands/ (**/*.md), plus command entries in the config (template, description). OpenCode expands them itself and never lists them.

MCP. mcp in the config: a local server has command as a list or a string, a remote one url. enabled: false turns a server off. Configs merge from the root to the start folder, and the deeper one wins.

Capture. ctxray runs opencode run --format json -m <provider>/<model> and sends the prompt on stdin. The config goes in through OPENCODE_CONFIG_CONTENT, with auto-update, model fetching, and LSP downloads off. When the harness's provider in your config is anthropic or openai, OpenCode talks to that provider through ctxray. Otherwise ctxray adds an OpenAI-compatible provider named ctxray, which speaks Chat Completions. Every OpenCode config along the chain in the copy gets its MCP servers routed through ctxray.

Install recipe. npm package opencode-ai, dist-tag latest. The native build is opencode-<os>-<arch>[-musl]@<version>, with windows in place of win32, executable bin/opencode. The wrapper's install script never runs, because it would write into your real home.

Cursor CLI

ctxray emulates the local build of Cursor CLI 2026.11.

Files. AGENTS.md, CLAUDE.md, and CLAUDE.local.md in any folder, rules in .cursor/rules/**/*.mdc (.MDC too, never .md), and the legacy .cursorrules at the root, which always applies.

.mdc frontmatter, line by line. Cursor doesn't parse a rule's frontmatter as YAML. It reads it line by line, so globs: *.ts works in Cursor although YAML rejects it, and ctxray reads it the same way. true and false become booleans, quotes come off, and a key with nothing after it collects the - item lines below it.

Activation, checked in this order:

Frontmatter Activation
alwaysApply: true (a real boolean, not "true") always
non-empty globs path, reason glob:<glob>, when a working file matches
description intent: the model picks the rule by its description, so only the description counts towards tokens
none of these manual: only when you mention it

AGENTS.md, CLAUDE.md, CLAUDE.local.md, and alwaysApply rules load from the root to the start folder as always. Deeper down, the same files load as path in each folder between the start folder and a file the agent read.

Three things work differently from the other harnesses, and ctxray follows them:

  • A glob without a slash matches from the rule's folder. globs: docker-compose*.yml in the root's .cursor/rules takes docker-compose.yml but not sub/docker-compose.dev.yml. Write **/docker-compose*.yml for any depth. Claude Code matches the same pattern at any depth.
  • Described rules come from the whole workspace. A rule with only a description is offered to the model at the start wherever it lives, sub/deep/.cursor/rules/ included.
  • A linked CLAUDE.md loads once. When CLAUDE.md and AGENTS.md in one folder are the same file through a symlink, Cursor loads it once, as AGENTS.md. Two separate files with the same text both load.

Skills. SKILL.md under .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/, or .grok/skills/. Subfolders count. The name is the frontmatter name or the folder, and a skill without a description is skipped. paths and disable-model-invocation: true work as in Claude Code. At launch the start folder's skills are listed, and a deeper folder's skills join once the agent reads a file there.

Commands. .cursor/commands/**/*.md. They belong to the Cursor editor, so nothing reaches the model in a headless run.

MCP. mcpServers in .cursor/mcp.json, in any folder of the chain.

Capture is experimental. Cursor CLI takes a base URL only in its hidden local build, cursor-agent-local. ctxray launches it as:

cursor-agent-local --authless --base-url <proxy>/v1 -p --output-format stream-json --trust --approve-mcps --force --disable-auto-update --model <model> <prompt>

Because that build is undocumented, capture stays off until you opt in:

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

Cursor CLI speaks Chat Completions, which has no token count endpoint, so its numbers stay estimates.

Install recipe. cursor-agent-local isn't on npm. ctxray reads the current version from https://cursor.com/install and downloads https://downloads.cursor.com/lab/<version>/<os>/<arch>/agent-cli-local-package.tar.gz, checked against the .sha256 file beside it. Builds exist for macOS and glibc Linux, x64 and arm64. The Cursor editor can't be installed by ctxray.

How a capture runs

L4 and up launch the harness (see The Loadout Stack). ctxray never runs it in your working tree or with your home:

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.

  1. ctxray copies the project into a temporary folder, with your uncommitted changes and with ignored instruction files such as CLAUDE.local.md. It appends a canary ⟦ctx:<path>⟧ to each instruction, skill, and command file in the copy, so it can tell which file reached the model.
  2. Each session gets its own folder with work, home, tmp, bin, and logs. The harness sees HOME, TMPDIR, and the XDG_* folders there, TERM=dumb, LANG=en_US.UTF-8, and TZ=UTC. A security shim in bin keeps it away from the macOS keychain.
  3. An egress guard sits in HTTPS_PROXY, HTTP_PROXY, and ALL_PROXY. It refuses and records every connection, so model traffic can only reach ctxray's proxy.
  4. On macOS, sandbox-exec denies writes outside the run folder. Other systems have no sandbox: run L4 and up in a container, as CI does.
  5. Stdio MCP servers are wrapped in ctxray's shim, and HTTP servers go through the proxy. Both keep a log of what the server said, so ctxray counts each tool's schema.

Your user-level files

By default a run sees none of your user-level files. Set userScope: "inherit" on a harness (Configuration) and ctxray copies them into the run's home. It copies files, never links them, and never copies a settings file, because one could point the harness past ctxray. Your MCP servers always run behind ctxray too.

Harness What comes along
Claude Code CLAUDE.md, rules, skills, agents, commands, output-styles from $CLAUDE_CONFIG_DIR or ~/.claude. MCP servers from ~/.claude.json, both the top-level ones and those of this project. Only hooks from your settings.json
Codex AGENTS.md, AGENTS.override.md, skills, prompts, hooks.json from $CODEX_HOME or ~/.codex, plus ~/.agents/skills. MCP servers from config.toml, where a project server of the same name wins
Gemini CLI GEMINI.md, skills, commands, agents from ~/.gemini (or $GEMINI_CLI_HOME/.gemini), plus ~/.agents/skills. mcpServers and hooks from your settings.json. Extensions stay out
OpenCode AGENTS.md, skills, commands, and agents from ~/.config/opencode (or $XDG_CONFIG_HOME/opencode), plus ~/.claude/CLAUDE.md, ~/.claude/skills, ~/.agents/skills. MCP servers from your config
Cursor CLI ~/.cursor/skills, ~/.cursor/commands, ~/.cursor/hooks.json, ~/.agents/skills, ~/.claude/skills, ~/.codex/skills, and MCP servers from ~/.cursor/mcp.json. Cursor keeps user rules in your account, so there are none to copy

Provisioning

The harness on your PATH is whatever version you last installed. That's fine for a quick look and wrong for CI. ctxray pins exact builds in ctxray.lock, installs them into its own cache, and runs them from there.

ctxray.lock

The lockfile sits next to your config, or in the current folder when there's no config. A run from a subfolder finds the config, and with it the same lockfile. It's JSON, with harnesses sorted by id. Only ctxray harness writes it, and you commit it.

{
  "lockfileVersion": 1,
  "harnesses": {
    "claude-code": {
      "source": "registry",
      "range": "2.1.325",                // what you asked for: a range, a version, or a tag
      "version": "2.1.325",              // what it resolved to
      "platforms": {                     // one build per platform, all of them at once
        "darwin-arm64": {
          "package": "@anthropic-ai/claude-code-darwin-arm64@2.1.325",
          "integrity": "sha512-Ds1f1B+qy2BWDI+VnmDHwkNyTbXCwFrBtrinPD95RBmUubFJu9nCzMgn+wrg5VwwF6vtkkzGexogneZIYZKb6A=="
        }
        // … linux-x64-glibc, linux-x64-musl, win32-x64, and the rest
      }
    },
    "codex": {
      "source": "system",                // run the one on PATH, record its version
      "version": "0.169.0"
    }
  }
}

One lockfile serves a Mac, a Linux runner, and Alpine, because harness add resolves every platform at once. ctxray checks each download against integrity: sha512-… from npm, sha256-… for Cursor's download.

Pinning and installing

ctxray harness add claude-code codex@0.169.x   # resolve and write ctxray.lock
ctxray harness install                         # install what the lock pins, like bun install
ctxray harness list                            # the lock against the config against this machine
  • harness add <id>[@range] takes the range from the argument, then from the harness's version in the config, then the recipe's dist-tag. It resolves an exact version and the integrity for every platform.
  • harness install installs every pinned harness for this machine. Each one ends as cache (already there), install (downloaded now), path (a system harness), or missing.
  • harness list shows what's pinned and whether this machine has it.
  • harness pack writes the pinned builds into one archive, ctxray-harnesses.tar by default, for this platform or the ones you name. harness install --from <archive> installs from it with no registry, which is the way into an offline machine (Enterprise).
  • harness upgrade <ids> moves a harness to the newest version its range allows, captures the starting context of the old and the new build on the mock model, and shows how the loadout changed. --dry-run leaves ctxray.lock as it was.

Every option is on Commands.

source: "system"

Some teams install harnesses with their own tooling. Set source: "system" and ctxray runs the harness it finds on PATH:

export default defineConfig({
  harnesses: { "claude-code": { source: "system" } },
});

ctxray harness add claude-code then records the version on PATH (probed with a throwaway home). ctxray doesn't upgrade a system harness: upgrade it on PATH, then run harness add again. A harness that's neither locked nor system also comes from PATH.

--frozen in CI

A lockfile that doesn't match the config is a problem: a harness missing from the lock, a system harness without its version, a changed source, or a config version other than the locked range. Locally ctxray only mentions it. With --frozen, ctxray test fails the tests that need that harness, and ctxray harness install downloads nothing and exits with code 4. In CI, and with --ci, --frozen is on by itself, for both commands.

--no-install

ctxray test installs a pinned harness the cache lacks on first use. ctxray test --no-install fails instead, which suits a runner that must not reach a registry.

The cache

Harness builds live in one cache per machine, shared by every project.

System Default folder
macOS ~/Library/Caches/ctxray
Windows %LOCALAPPDATA%\ctxray\Cache
Linux $XDG_CACHE_HOME/ctxray, or ~/.cache/ctxray
  • CTXRAY_CACHE_DIR replaces the default folder. A relative path resolves from the folder ctxray starts in, and so do relative entries of CTXRAY_CACHE_DIRS.
  • CTXRAY_CACHE_DIRS lists several folders, separated by : (; on Windows). ctxray searches all of them in order, and the first writable one takes new installs. The others are read-only layers, such as a cache on NFS or one baked into a runner image, and ctxray never prunes them.

Inside, each build sits in harnesses/<harness>/<version>+<platform>+<sha8>/. Two processes that install at once take turns, and a build appears only after its integrity check passed.

ctxray cache dir                    # the writable folder, for a CI cache step
ctxray cache ls                     # builds across every layer
ctxray cache prune --older-than 14  # builds unused for 14 days
ctxray cache prune --all            # every build ctxray.lock doesn't pin
ctxray cache clear --yes            # every build, pinned ones too

cache prune keeps the builds your ctxray.lock pins. CI Integration shows cache dir in a cache step.

Platform keys

The lockfile and the cache name platforms by these keys:

Key Machine
darwin-arm64 macOS on Apple silicon
darwin-x64 macOS on Intel
linux-x64-glibc Linux x64 with glibc
linux-x64-musl Linux x64 with musl, such as Alpine
linux-arm64-glibc Linux arm64 with glibc
linux-arm64-musl Linux arm64 with musl
win32-x64 Windows x64
win32-arm64 Windows arm64

ctxray detects musl by the loader /lib/ld-musl-*. harness pack --platform takes these keys, comma-separated, or all.

Registries, proxies, and .npmrc authentication are on Enterprise.

Clone this wiki locally