Skip to content

Getting Started

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

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

ctxray is one executable with no runtime to install. Pick the channel you already use, then follow Your first session on your own repository.

Install

npm

npm install -g @mairwunnx/ctxray

Or run it once without installing:

npx @mairwunnx/ctxray inspect
bunx @mairwunnx/ctxray inspect

The @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/ctxray

Homebrew

On macOS and Linux:

brew install mairwunnx/tap/ctxray

Scoop

On Windows:

scoop bucket add mairwunnx https://github.com/MairwunNx/scoop-bucket
scoop install mairwunnx/ctxray

Install scripts

On macOS and Linux:

curl -fsSL https://github.com/MairwunNx/ctxray/releases/latest/download/install.sh | sh

On Windows, in PowerShell:

irm https://github.com/MairwunNx/ctxray/releases/latest/download/install.ps1 | iex

Both 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 sh

Alpine 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++ libgcc

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

Docker

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 test

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

Release archives and offline machines

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 --version

Verify a download

Every 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        # macOS

SHA256SUMS 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.com

Every 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/ctxray

The release also carries ctxray.cdx.json, a CycloneDX SBOM of the dependencies the executable bundles.

System requirements

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.

Your first session

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.

1. See what your agents load

Run inspect in the project root:

ctxray inspect

ctxray 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 · cwd loads 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.md because CLAUDE.md imports it. An unconditional rule in .claude/rules shows just always. 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.

2. Create a config and a test

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.

3. Run the tests

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.

4. Pin the harnesses and commit ctxray.lock

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.

5. Run it in CI

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.

Clone this wiki locally