Repository navigation
Getting Started
ctxray is one executable with no runtime to install. Pick the channel you already use, then follow Your first session on your own repository.
npm install -g @mairwunnx/ctxrayOr run it once without installing:
npx @mairwunnx/ctxray inspect
bunx @mairwunnx/ctxray inspectThe @mairwunnx/ctxray package holds a small ctxray launcher and the types for your editor. The executable itself comes in a platform package, one per system, the way esbuild and Biome ship theirs: npm installs only the one whose os, cpu, and libc match your machine.
| Platform package | For |
|---|---|
@mairwunnx/ctxray-linux-x64, @mairwunnx/ctxray-linux-arm64
|
Linux with glibc |
@mairwunnx/ctxray-linux-x64-musl, @mairwunnx/ctxray-linux-arm64-musl
|
Alpine and other musl systems |
@mairwunnx/ctxray-darwin-arm64, @mairwunnx/ctxray-darwin-x64
|
macOS |
@mairwunnx/ctxray-windows-x64, @mairwunnx/ctxray-windows-arm64
|
Windows |
The launcher runs on Node or Bun and hands over to the executable. If it says npm didn't install a binary for your platform, you probably installed with --omit=optional: reinstall without it. If it warns that the launcher and the binary have different versions, reinstall to line them up.
To get the types in ctxray.config.ts and your tests, add the package to the project as well. ctxray runs the tests without it.
npm install -D @mairwunnx/ctxrayOn macOS and Linux:
brew install mairwunnx/tap/ctxrayOn Windows:
scoop bucket add mairwunnx https://github.com/MairwunNx/scoop-bucket
scoop install mairwunnx/ctxrayOn macOS and Linux:
curl -fsSL https://github.com/MairwunNx/ctxray/releases/latest/download/install.sh | shOn Windows, in PowerShell:
irm https://github.com/MairwunNx/ctxray/releases/latest/download/install.ps1 | iexBoth scripts pick the build for your system, download it with SHA256SUMS, and refuse to install when the checksum doesn't match. install.sh puts ctxray into ~/.local/bin and tells you when that folder isn't on your PATH. install.ps1 puts ctxray.exe into %LOCALAPPDATA%\Programs\ctxray and adds it to your user PATH, so open a new terminal afterwards.
These variables change what the scripts do:
| Variable | What it does | Default |
|---|---|---|
CTXRAY_VERSION |
Installs this version, like 0.1.0
|
the latest release |
CTXRAY_DOWNLOAD_BASE |
Downloads from a mirror instead of GitHub. The mirror keeps GitHub's layout: <base>/latest/download/<asset> and <base>/download/v<version>/<asset>
|
https://github.com/MairwunNx/ctxray/releases |
CTXRAY_INSTALL_DIR |
Where the executable goes |
~/.local/bin, or %LOCALAPPDATA%\Programs\ctxray on Windows |
CTXRAY_LANG |
The language of the script's messages, en or ru
|
your system's language |
curl -fsSL https://github.com/MairwunNx/ctxray/releases/latest/download/install.sh \
| CTXRAY_VERSION=0.1.0 CTXRAY_INSTALL_DIR=/usr/local/bin shAlpine and other musl systems. install.sh picks the musl build by itself. That build links against libstdc++ and libgcc, which Alpine leaves out, so install them first:
apk add libstdc++ libgccThe script still installs ctxray without them, and tells you what to add.
Older x64 processors. The regular Linux x64 build needs AVX2. On a Linux x64 machine without it, install.sh takes ctxray-linux-x64-baseline.tar.gz instead. npm and Homebrew can't tell such a machine apart, so there use the script or the release archive.
On macOS under Rosetta, the script installs the native Apple silicon build, which runs faster.
Two images live on ghcr.io/mairwunnx/ctxray, for linux/amd64 and linux/arm64:
| Tag | What's inside | For |
|---|---|---|
latest, <version>
|
the executable alone, on distroless |
ctxray inspect and layers L1–L3 |
runtime, <version>-runtime
|
plus git and Node | layers L4 and up, which launch harnesses |
Mount your project at /work, the images' working folder:
docker run --rm -v "$PWD:/work" ghcr.io/mairwunnx/ctxray inspect
docker run --rm -v "$PWD:/work" ghcr.io/mairwunnx/ctxray:runtime testThe images never carry the harnesses themselves: ctxray installs the ones your ctxray.lock pins. To bake them into your own CI image, see CI Integration.
Each release carries one archive per platform: ctxray-<platform>.tar.gz, or .zip on Windows. The names hold no version, so releases/latest/download/<asset> always points at the newest.
| Platform | Archive |
|---|---|
| Linux x64, arm64 (glibc) |
ctxray-linux-x64.tar.gz, ctxray-linux-arm64.tar.gz
|
| Linux x64 without AVX2 | ctxray-linux-x64-baseline.tar.gz |
| Linux musl |
ctxray-linux-x64-musl.tar.gz, ctxray-linux-arm64-musl.tar.gz
|
| macOS |
ctxray-darwin-arm64.tar.gz, ctxray-darwin-x64.tar.gz
|
| Windows |
ctxray-windows-x64.zip, ctxray-windows-arm64.zip
|
An archive is a complete offline bundle. Next to the executable it holds the JSON Schemas in schemas/, the GitLab template ctxray.gitlab-ci.yml, harnesses.Dockerfile, and the Claude Code plugin as ctxray-claude-plugin.zip. Carry one archive into a closed network and you have everything ctxray ships. For the harnesses on such a machine, see ctxray harness pack in Enterprise.
tar -xzf ctxray-linux-x64.tar.gz
./ctxray --versionEvery release lists the SHA-256 of each file in SHA256SUMS. Check the files you downloaded against it:
sha256sum --check --ignore-missing SHA256SUMS # Linux
shasum -a 256 --check --ignore-missing SHA256SUMS # macOSSHA256SUMS is signed with Sigstore, keylessly, by the release workflow. The signature sits next to it as SHA256SUMS.sigstore.json. Check it with cosign, and you know the checksums came from ctxray's own release run:
cosign verify-blob SHA256SUMS \
--bundle SHA256SUMS.sigstore.json \
--certificate-identity-regexp '^https://github.com/MairwunNx/ctxray/\.github/workflows/release\.yml@' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comEvery release file also carries a GitHub build provenance attestation. The GitHub CLI checks it file by file:
gh attestation verify ctxray-linux-x64.tar.gz --repo MairwunNx/ctxrayThe release also carries ctxray.cdx.json, a CycloneDX SBOM of the dependencies the executable bundles.
ctxray runs on macOS, Linux, and Windows, on x64 and arm64. It needs 1 GB of memory, enough for every layer and every harness with room to spare. The tightest that still works is 768 MB, or 512 MB without Gemini CLI.
| What runs | Memory | Time |
|---|---|---|
inspect and test L1–L3 for Claude Code, a small project |
110 MB | 0.1 s |
| The same for all five harnesses | 380 MB | 0.4 s |
| All five harnesses on a monorepo of 87,000 files | 620 MB | 5 s |
Gemini CLI costs the most: ctxray counts its tokens with the Gemma vocabulary, and loading it takes about 300 MB. The other harnesses count with o200k, which fits in a few megabytes.
L4–L7 launch the harness itself, and its memory adds to ctxray's own:
| Harness | One session | On disk in the cache |
|---|---|---|
| Claude Code | 300 MB | 280 MB |
| Codex | 180 MB | 420 MB |
| Gemini CLI | 230 MB | 100 MB |
| OpenCode | 560 MB | 200 MB |
| Cursor CLI | 530 MB | 400 MB |
ctxray runs one session at a time. An L6 or L7 test with concurrency above 1 runs several side by side, and each extra one adds a session from the table: concurrency: 4 with OpenCode wants about 2.5 GB.
The executable takes 130 MB on disk. The numbers are peak memory per process on Linux arm64 in Docker, the minimums come from docker run --memory. macOS comes out within a few dozen megabytes of them. Windows isn't measured yet.
The steps below run on the payments example from ctxray's own fixtures: a Kotlin project with rules, skills, and MCP servers for Claude Code, Codex, Gemini CLI, OpenCode, and Cursor. Your repository works the same way.
Run inspect in the project root:
ctxray inspectctxray reads the files of every harness and prints what each one loads, without launching any of them. Add --files to say which files the agent works with, and the rules for them load too:
ctxray inspect --harness claude-code --files app/src/main/kotlin/payments/Charge.kt ~/payments · the agent starts in .
and works with app/src/main/kotlin/payments/Charge.kt
Claude Code ≈ 286
Rules ≈ 219
CLAUDE.md ≈ 63 always · cwd
AGENTS.md ≈ 23 always · import:CLAUDE.md
.claude/rules/style.md ≈ 12 always
app/CLAUDE.md ≈ 23 path · nested:app/src/main/kotlin/payments/Charge.kt
.claude/rules/payments.md ≈ 15 path · glob:**/payments/**/*.kt
…
Skills ≈ 48
refunds ≈ 19 .claude/skills/refunds/SKILL.md
android-build ≈ 18 app/.claude/skills/android-build/SKILL.md
…
Commands ≈ 19
changelog .claude/commands/changelog.md
MCP servers after a run
github .mcp.json
jira .mcp.json
System prompt and built-in tools after a run
⚠ .claude/rules/web.md No file in the repository matches frontend/**/*.tsx, so the rule never loads dead-rule
≈ marks a local estimate with the o200k_base+calibrated:claude-sonnet-5-5 tokenizer
The system prompt, built-in tools, and MCP tool schemas get counted once ctxray launches the harness
Here is how to read it:
- ≈ and the numbers. Each piece shows its tokens. ctxray counts them locally, so they're estimates and carry ≈. The footer names the tokenizer behind them. Concepts explains the counting.
-
Activation and reason. The last column of a rule says when it loads and why it loaded now.
always · cwdloads in every session started here.path · nested:…loaded because the agent works with a file below that folder,path · glob:…because a file matched the rule's glob,import:CLAUDE.mdbecauseCLAUDE.mdimports it. An unconditional rule in.claude/rulesshows justalways. Concepts lists every kind and reason. - Skills and commands show where they come from. The skill's tokens are what the model sees in the skill list: its name and description, not the whole body.
- after a run. Reading files can't tell what an MCP server's tools cost, or how long the harness's own system prompt is. ctxray counts those once it launches the harness, in layer L4.
-
Warnings. A line with ⚠ names the file, says what's wrong, and ends with the check's id, here
dead-rule. The id is what you name to turn a check down in Configuration.
Run inspect without --harness and you'll also see harness-differences warnings, like “Codex doesn't read this file, and nothing it reads says the same, so the harnesses get different instructions”. Concepts explains them.
ctxray init ✓ created ctxray.config.ts
✓ created ctxray/loadout.ctxray.ts
Next: describe your agent setup in ctxray/loadout.ctxray.ts and run ctxray test
ctxray.config.ts names the harnesses to test, Claude Code and Codex to start with:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: {
"claude-code": {},
codex: {},
},
});ctxray/loadout.ctxray.ts checks that each harness loads its root rules file:
import { expect, suite, test } from "@mairwunnx/ctxray";
// The root rules file each harness reads.
const rootRules: Record<string, string> = { "claude-code": "CLAUDE.md", codex: "AGENTS.md" };
suite("loadout", () => {
test.resolve("the root rules file loads for every file", async ({ harness, resolve }) => {
const loadout = await resolve({ files: ["README.md"] });
expect(loadout.rules).toInclude(rootRules[harness]);
});
});init never overwrites a file that exists, unless you pass --force. When the project has a .gitignore, init adds .ctxray/ to it: reports and traces land there. Configuration covers every key, and Writing Tests the test API.
ctxray test ctxray 0.1.0 · 2 harnesses · backend: mock
ctxray checks
L1 lint project files
claude-code ✓ 1 warning codex ✓ 7 warnings
L4 assemble starting context
claude-code ✓ ≈ 17,043 tokens codex ○ no codex on PATH
loadout
L3 resolve the root rules file loads for every file
claude-code ✓ codex ✓
⚠ claude-code › L1 lint › project files
.claude/rules/web.md No file in the repository matches frontend/**/*.tsx, so the rule never loads dead-rule
…
Layers L1 ✓ 2 L3 ✓ 2 L4 ✓ 1
Total 5 passed · 1 skipped · 1.5 s
ctxray runs its own checks next to your tests. L1 lints the files of each harness, and L4 launches each harness against a mock model to measure the context it really starts with. That launch costs nothing: no model is called. Your test ran at L3, which only reads files. The Loadout Stack explains every layer.
Codex was skipped at L4 because this machine has no codex on its PATH. The next step fixes that. Before L4, ctxray doctor checks that git, the network, and the cache are in place.
ctxray harness add claude-code codex ✓ claude-code 2.1.311 (stable) added
✓ codex 0.169.0 (latest) added
Wrote ctxray.lock
ctxray.lock records the exact version of each harness and the checksum of its build for every platform. ctxray installs a pinned harness into its own cache on first use, so your machine and CI run the same builds. Run ctxray test again and Codex passes L4 too:
L4 assemble starting context
claude-code ✓ ≈ 17,021 tokens codex ✓ ≈ 8,227 tokens
Commit the config, the lockfile, and the tests:
git add ctxray.config.ts ctxray.lock ctxray/
git commit -m "test: check what the agents load"Harnesses covers harness install, upgrade, and the cache.
In CI, or with --ci, ctxray turns on --frozen by itself: a lockfile that doesn't match the config fails the run. Add the GitHub Action or the GitLab template next, as CI Integration shows.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие