Tracegate CI

Tracegate CI

Local CI for TypeScript that runs only the tests a change can affect, and has to earn the right to skip the rest.

Tracegate records what each test file touches when it runs: the functions it executes, the modules it loads, and the files it reads. When you change code, a test whose recorded inputs didn't change can reuse its last green result. The rest run.

It doesn't skip anything until that has been shown to be safe:

• Shadow first. Every test still runs, and Tracegate logs what it would have skipped.
• Entry bar. A lane starts skipping only after 20 runs over 14 days, with no untriaged miss in the last 14 days.
• Random audits. 5% of the skippable tests run anyway.
• A miss suspends it. If a test predicted safe to skip fails anyway, the lane runs everything for 14 days, unless someone triages the miss as a flaky test.

It can't turn a red into a green. A failing test's record is dropped, and no record older than 72 hours is reused.

Tracegate came out of a private TypeScript monorepo with about 3,700 test files, where it gates every merge. Its measured miss rate there is published in docs/evidence/.

Install

npm install --save-dev tracegate-cinpx tracegate init --write --mcp   # writes tracegate.config.json and wires the recordernpx tracegate doctor --canary      # checks the setup by recording one test filenpx tracegate run                  # runs the lane; in shadow, everything still runsnpx tracegate savings              # what skipping would have saved so far

init without --write only prints what it would do. It never overwrites an existing config, and it tells you which Vitest configs to edit by hand.

Requirements: Node 22+, git, Vitest 4.1–5.x or Jest 30, and TypeScript 5 or 6 in your repository. On TypeScript 7, also install 6 under an alias Tracegate looks for: npm i -D tracegate-typescript@npm:typescript@6.

Claude Code plugin

/plugin marketplace add davidscotttufts/tracegate-ci/plugin install tracegate@tracegate

The plugin adds an MCP server, two subagents (red-reader, deps-oracle), two skills, and a hook. In a Tracegate repository, the hook stops agents from running a bare vitest or npm test outside the queue, and from triaging misses or approving skipped tests themselves. TRACEGATE_HOOK=off turns it off.

What the plugin runs and touches (also in PRIVACY.md):

• Runs: node on its own files (the MCP server over stdio, and the hook), git, your test runner, the commands you give tracegate lease, and ssh-keygen or gpg when you run attest.
• Reads: your repository and its history, test coverage, and this machine's load and memory (ps, vm_stat, sysctl and pmset on macOS; /proc on Linux).
• Writes: its ledger in .git/tracegate/, temporary files and a socket in the OS temp directory, git notes under refs/notes/tracegate when you run attest, and the files init --write lists.
• Sends: nothing by default: no telemetry and no network calls. Two features you turn on yourself use the network through your own login: attest --status posts a GitHub commit status with gh, and the release bus reads and writes a GCS bucket you name, with gcloud.
• Installs: nothing. The package has no runtime dependencies.

How it decides

A test reuses its last green result when nothing it depends on has changed since. That means no change to:

• a function it executed, a constant it uses, or a module it loaded;
• a file it read;
• the test file itself;
• a global input, such as package.json, a lockfile or the Vitest config;
• the repository's history, for a test that runs git on it.

Uncommitted edits count. Edits inside functions the test never ran don't.

What a recording can't see is the clock, environment variables, the network, and other processes. The 72-hour limit, the random audit, and a full run at least once a day cover those. The full rules are in How a decision is made.

Commands

tracegate --help lists every command and flag.

Configuration

tracegate init --write creates tracegate.config.json. A lane is one test project:

{  "lanes": {    "api": { "dir": "packages/api", "src": "src", "globals": ["test/setup/"] },    "web": { "dir": "packages/web", "src": "src" }  }}

List your test setup directory under globals: every test loads it, so a change there runs the whole lane. All settings are in the guide.

What else is in the box

Why not Vitest's recordDependencies? The comparison runs both on the same commits. Tracegate selects per function, sees files read at run time, and audits its own skips.

More

• Guide: the full reference.
• Roadmap and changelog.
• Background: the research and measurements behind the design.
• Recipes: with claude-code-merge-queue, edit-level guards, worktrees, and a bin/ci script.

Apache-2.0. See LICENSE and NOTICE.