Skip to content

Contributing

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

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

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.

Setup

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 install

Run 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 --help

Try 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

Commands

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.

Rules

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.md and Feature-Action-Architecture/examples/ts-bun.md. Imports go only downward, through each slice's index.ts and 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.ts fails 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:test for 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 a test.each table.
  • 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.ts is the source, and Russian in locales/ru/index.ts ships with it. A hard-coded user-facing string is a bug. Add each new key to both catalogs: the type check and catalogs.test.ts fail 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 and the changelog

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.

Adding a harness adapter

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.

  1. The id. Add it to HarnessId in shared/contract/harness.ts. The config schema, the lockfile, and the published JSON Schemas take it from there.
  2. The profile. Add a HarnessProfile to PROFILES in entities/harness/profiles.ts: its modes and the capabilities it really has. profiles.test.ts checks, for one, that a harness with capture is also headless and proxyable.
  3. Discovery and resolution. Create entities/harness/<id>/ with discover.ts, which finds every file the harness could load and returns an Inventory, and resolve.ts, which predicts what loads for a working folder and a set of files. Register both in STATIC_ADAPTERS in entities/harness/adapters.ts.
  4. Locations. Tell entities/harness/locations.ts which file locations the harness reads, so the reach check can warn when harnesses get different instructions.
  5. Static tests. Add a fixture project under packages/ctxray/fixtures/static/ and test discovery, activation, and lint findings against it, with test.each tables. Name in a comment the version of the harness the code emulates.
  6. 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 through context.shim and context.remote. Write version() too.
  7. Segments. Write segment.ts, which cuts a captured request into system, rules, skills, mcp, commands, tools, and messages, and capture.ts with the CaptureAdapter, including call(), which turns a test's intent into the harness's own tool call. Register it in CAPTURE_ADAPTERS. A harness that speaks a wire protocol ctxray doesn't know yet also needs a kit in entities/proxy/protocols/.
  8. Payloads. Add the harness to packages/ctxray/fixtures/capture/ctxray.config.ts, pin it with ctxray harness add in that folder, and record its real requests (below). Write the segmenter's contract tests against the recorded payloads.
  9. Installs. Add a Recipe to RECIPES in entities/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.
  10. User scope. Teach capture/user-scope.ts and capture/user-mcp.ts which user-level rules, skills, and MCP servers userScope: "inherit" brings along.
  11. Words and docs. New lint messages go into both catalogs. Update the Harnesses page and the README's table of supported agents.

Recording payloads

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      # one

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

CI and the autopilot

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.

Releases

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@next

Clone this wiki locally