Repository navigation
Contributing
Thanks for helping with ctxray. This page gets you from a fresh clone to a pull request: the setup, the checks, the rules the code follows, and how to add a harness. Architecture explains how the code fits together.
You need git and Bun. The root package.json pins Bun's version in packageManager, so install that one. The Feature-Action Architecture rules come as a git submodule:
git clone https://github.com/MairwunNx/ctxray.git
cd ctxray
git submodule update --init
bun installRun the CLI straight from the source, with no build step:
bun packages/ctxray/src/app/main.ts inspect
bun packages/ctxray/src/app/main.ts test --helpTry it on a copy of a fixture, never in the repository itself, and keep the harness cache in a folder of its own:
repo="$PWD"
dir="$(mktemp -d)"
cp -R packages/ctxray/fixtures/capture/. "$dir/project"
cd "$dir/project" && git init -q
CTXRAY_CACHE_DIR="$dir/cache" bun "$repo/packages/ctxray/src/app/main.ts" test --plain| Command | What it does |
|---|---|
bun run check |
Biome, the type check (the CLI and the HTML report's page script), and the file size limit. CI runs the same |
bun test |
The unit tests |
bun run fix |
Biome's safe fixes and formatting, biome check --write .
|
bun run build |
Compiles the executable for this machine into dist/ctxray
|
bun run typecheck |
The type check alone |
bun run schemas |
Writes the published JSON Schemas into dist/schemas
|
bun run gitleaks |
Regenerates the redaction rules from gitleaks |
Run bun run check and bun test before every commit.
These rules hold for every change. Review sends back a change that breaks one.
- Stack. Bun, TypeScript in strict mode, and Elysia, nothing else.
-
Architecture. Feature-Action Architecture, strictly. Read
Feature-Action-Architecture/AI.mdandFeature-Action-Architecture/examples/ts-bun.md. Imports go only downward, through each slice'sindex.tsand its#alias (Architecture). -
Dependency injection. typed-inject, with factories that take their dependencies as positional parameters and name them in
.inject. Not the(deps: Deps) => …shape from the FAA README: typed-inject passes arguments by position. No service classes with state where a function will do, no global singletons. - The simplest code. No abstractions “for later”. Explicit beats magic.
-
Small files. Aim for about 120 lines, never more than 200.
scripts/check-file-size.tsfails CI on a longer code file. i18n catalogs and fixtures are exempt. - Biome only. It lints and formats. No ESLint, no Prettier.
-
Unit tests with
bun:testfor logic: resolvers, normalisation, harness config parsing, statistics, redaction, locale resolution, plurals, policies, report lines, matrix expansion. Skip the trivial. Where one behaviour meets many inputs, harnesses and locales above all, write atest.eachtable. - No telemetry, no network by default. ctxray talks only to the registry and the upstream the user configured.
- Secrets stay out. Secrets and personal data never reach traces, logs, reports, or snapshots in clear text. Redaction runs before anything is written to disk.
-
Hands off the user's files. A test run never touches the user's working tree: fixtures and canaries live in a temporary copy. Harness runs never touch the real home folder either:
~/.claude,~/.codex,~/.gemini,~/.config/opencode,~/.cursor, and the macOS keychain stay as they were. -
Every string a user sees goes through the i18n catalog. English in
packages/ctxray/src/shared/i18n/locales/en/index.tsis the source, and Russian inlocales/ru/index.tsships with it. A hard-coded user-facing string is a bug. Add each new key to both catalogs: the type check andcatalogs.test.tsfail when a key, a plural form, or a placeholder is missing. Localization has the details. - English in the code. Code, comments, identifiers, and commit messages are English.
Commits follow Conventional Commits in English, one logical change per commit, and each commit builds and passes its tests:
feat(proxy): count Gemini's cached tokens
fix(i18n): Russian plural for “harnesses”
chore(ci): update actions/checkout to v8
docs(wiki): the GitLab merge request job
CHANGELOG.md holds one section per version, ## 0.2.0. When your change reaches what ctxray ships (the CLI, the npm package, the images, the plugin), add a line to the topmost section that isn't released yet, or open a section for the next version. The release takes its notes from that section, so write for the people who install ctxray, not for its developers. Changes to CI or development tools need no entry.
A harness joins ctxray in steps, and each step works on its own: static first, then capture, then installs. Read the folder of a harness close to yours before you start: codex for a CLI that speaks OpenAI Responses, gemini-cli for one that runs on Node.
-
The id. Add it to
HarnessIdinshared/contract/harness.ts. The config schema, the lockfile, and the published JSON Schemas take it from there. -
The profile. Add a
HarnessProfiletoPROFILESinentities/harness/profiles.ts: its modes and the capabilities it really has.profiles.test.tschecks, for one, that a harness withcaptureis alsoheadlessandproxyable. -
Discovery and resolution. Create
entities/harness/<id>/withdiscover.ts, which finds every file the harness could load and returns anInventory, andresolve.ts, which predicts what loads for a working folder and a set of files. Register both inSTATIC_ADAPTERSinentities/harness/adapters.ts. -
Locations. Tell
entities/harness/locations.tswhich file locations the harness reads, so the reach check can warn when harnesses get different instructions. -
Static tests. Add a fixture project under
packages/ctxray/fixtures/static/and test discovery, activation, and lint findings against it, withtest.eachtables. Name in a comment the version of the harness the code emulates. -
Launch. Write
launch.ts: the command line for a headless run, the environment that points the harness at ctxray's proxy with a dummy key, and the config files it needs inside the run's home, with telemetry and updates off. Route its MCP servers throughcontext.shimandcontext.remote. Writeversion()too. -
Segments. Write
segment.ts, which cuts a captured request intosystem,rules,skills,mcp,commands,tools, andmessages, andcapture.tswith theCaptureAdapter, includingcall(), which turns a test's intent into the harness's own tool call. Register it inCAPTURE_ADAPTERS. A harness that speaks a wire protocol ctxray doesn't know yet also needs a kit inentities/proxy/protocols/. -
Payloads. Add the harness to
packages/ctxray/fixtures/capture/ctxray.config.ts, pin it withctxray harness addin that folder, and record its real requests (below). Write the segmenter's contract tests against the recorded payloads. -
Installs. Add a
RecipetoRECIPESinentities/harness-cache/recipes.ts: the npm package, its default dist-tag, the per-platform build, and where the executable sits. No install script ever runs. -
User scope. Teach
capture/user-scope.tsandcapture/user-mcp.tswhich user-level rules, skills, and MCP serversuserScope: "inherit"brings along. - Words and docs. New lint messages go into both catalogs. Update the Harnesses page and the README's table of supported agents.
The segmenters' contract tests run against real requests each harness sent, kept in packages/ctxray/fixtures/payloads/. After a harness upgrade, record them again:
(cd packages/ctxray/fixtures/capture && bun ../../src/app/main.ts harness install)
bun scripts/record-payloads.ts # every harness
bun scripts/record-payloads.ts codex # oneThe script launches each harness on the capture fixture against the mock model, as the fixture's ctxray.lock pins it from the cache, or from PATH when the cache lacks it. It replaces the copy's folder, the run's home, and the cache path with stable placeholders, so the files don't change from machine to machine. Then bun test shows what moved: fix the segmenter when a harness changed its markers.
| Workflow | What it does |
|---|---|
ci.yml |
On every push and pull request: Biome, the type check, the file size limit, the tests, the build, smoke tests of the executable, the config, the test runner, and capture with every pinned harness, and validation of the Claude Code plugin |
autopilot-biome.yml |
Called by CI when Biome fails: Claude fixes what Biome reports and commits to the same branch, once |
autopilot.yml |
Every Monday: Claude runs the update-deps skill, updates every dependency, and starts CI on the result |
release.yml |
Run by hand: releases the version typed into it, with its notes from CHANGELOG.md
|
release-build.yml |
Called by Release and Next: builds every platform and installs each build the way a user would |
release-packages.yml |
Called by Release and Next: publishes to npm and ghcr.io |
next.yml |
Every push to master: ships to the next channel, once the repository variable NEXT_CHANNEL is "true"
|
The update-deps skill in .claude/skills/update-deps/SKILL.md describes what moves together in an update: Bun with @types/bun, Biome with its schema URL, the gitleaks rules, the submodule, and the harnesses the capture fixture pins. Read it before you update a dependency by hand.
Only the owner releases, or an agent the owner asks. CHANGELOG.md gets a section for the new version, like ## 0.1.1. Then the owner starts Actions → Release → Run workflow and types the version into its field, or runs gh workflow run release.yml -f version=0.1.1 -f dry-run=false. The workflow writes the version into package.json and plugin.json of its build and takes the notes from that section, unless its changelog field holds others. It runs as a dry run by default: it builds and checks everything and publishes nothing.
A real release creates the GitHub release with signed checksums and build attestations, publishes the npm packages and the images, and updates the Homebrew tap, the Scoop bucket, and the action's repository with its tags v<version> and v0.
Between releases, once the NEXT_CHANNEL variable is on, every push to master ships to the next channel: npm's next dist-tag and the images :edge and :edge-runtime. The version is the patch after the newest release tag with the run number, like 0.1.1-next.42, so it sorts above the release it follows:
npm install -g @mairwunnx/ctxray@nextStart
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие