Repository navigation
Releases
Releases Β· MairwunNx/ctxray
ctxray 0.1.0
The first release. ctxray shows what your AI agents load into a model's context and tests it in CI.
- π
ctxray inspectshows what loads here. Rules, skills, commands, and MCP servers of Claude Code, Codex, Gemini CLI, OpenCode, and Cursor CLI, each with its tokens and the reason it loaded: always, for a file path you pass with--files, or by its description. Claude Code Desktop and the Cursor editor read the same files, ask for them with--harness. A warning names what one agent sees and another doesn't, like aCLAUDE.mdCodex never reads. - πͺ Tokens counted each agent's way. Claude's count comes from o200k with factors measured on
claude-sonnet-5-5, Gemini's from the Gemma vocabulary, the others' from o200k. Every local count carries β. WithexactTokens, ctxray asks the provider for the exact number through your key. - β
Tests in seven layers.
*.ctxray.tsfiles holdtest.resolve,test.assemble,test.wire,test.activate, andtest.scenario, from what the files predict (L3) to a task the agent solves end to end (L7). ctxray runs L1 Lint and L2 Policy itself.ctxray initwrites a config and a first test that passes. - π§ͺ One test, every agent. A test runs once per harness in the config, and
expect.onnarrows a check to some of them.discover.rules()turns one test into one per rule, by CODEOWNERS owner, folder, or activation. - π― Does the model pick the right skill?
test.activatesends prompts to a real model several times and checks the share of runs that loaded the skill, with a 95% Wilson interval. By default a skill must load in 80% of the runs, and a test makes the 16 runs it takes to prove that. The config'sactivatesets both for your project. Too few runs to tell givesinconclusive, not a guess.--recordkeeps the model's answers, and--backend replayplays them back for free on every merge request.ctxray gen-promptswrites prompts from the descriptions for you to review. - π°οΈ What the agent really sent. L4 and L5 launch the agent on a copy of your project behind ctxray's proxy, with an isolated home, no network but the proxy, and a mock model: free and the same every run. You see the system prompt, the built-in tools, and every MCP tool with its schema's tokens.
- π¦ Pinned agents.
ctxray harness addpins versions inctxray.lockwith integrity for every platform, and CI installs exactly those from npm or your registry.harness upgradeshows how a new version changes the context.harness packandinstall --fromcarry them into a network without internet. - π Your organisation's rules. Policies limit tokens per component, ban or require MCP servers, and require files.
extendsshares them from an npm package.ctxray baselinelets an old repository adopt ctxray and fail only on new problems. 27 lint checks catch broken frontmatter, dead rules, missing imports, and skills an agent never sees. - π What a merge request changes.
ctxray diffcompares the loadout withorigin/masteror the--baseyou name. - π Your own sessions.
ctxray spectate installadds hooks to Claude Code and Cursor, andctxray spectateshows what your latest sessions loaded. Prompts never get stored. - π§© A plugin for Claude Code.
/ctxrayshows what the current session loaded,/ctxray-testruns the tests, and thewrite-testsskill writes them.ctxray mcpservesinspect,run, anddiffto any agent. - π Reports. A live view in the terminal, an HTML report in English and Russian that
ctxray show-reportkeeps live while tests run, JUnit, Allure, JSON, and a Markdown summary that lands in the GitHub job summary. - π’ Closed networks. LLM gateways, proxies, your CA certificates, internal npm registries with
.npmrcauth, read-only shared harness caches, and anofflineswitch.ctxray doctorchecks all of it first. - π Secrets stay out. Keys, tokens, emails, phone and card numbers are hidden before anything reaches a trace, a report, a snapshot, or a cassette, with gitleaks' rules on top of ctxray's own.
- π Install it your way. npm, Homebrew, Scoop,
install.shandinstall.ps1, Docker images on ghcr.io, a GitHub Action, a GitLab CI template, and release archives that work as offline bundles. Executables for Linux (glibc and musl, x64 and arm64, and x64 without AVX2), macOS, and Windows on x64 and arm64. Checksums are signed with Sigstore and the files carry build attestations and an SBOM. - π English and Russian. ctxray follows your system's language, or
--lang.
npm install --save-dev @mairwunnx/ctxray@0.1.0
curl -fsSL https://github.com/MairwunNx/ctxray/releases/download/v0.1.0/install.sh | CTXRAY_VERSION=0.1.0 sh
brew install mairwunnx/tap/ctxray
docker pull ghcr.io/mairwunnx/ctxray:0.1.0