ctxd

A context firewall for AI coding agents.

Local-first engineering memory that gives Claude Code, Cursor and friends the minimum useful context for a task — and explains every token it sent.

The problem

You paste your repo into an AI agent. It gets 60,000 tokens, most of it irrelevant, and still misses the one architectural rule that mattered. Next session you explain the same project again. And again.

Meanwhile the agent "helpfully" reformats a file you asked it to change one line in.

What ctxd does

$ ctxd context --task "Fix Stripe webhook idempotency" --budget 10000

CONTEXT RECEIPT 87f27bbb

Candidate: 76,182 estimated tokens
Final:     4,547 estimated tokens
Estimated context avoided: 71,635

Included (16):
  ✓ docs/rules.md                       [P0]  reason: mandatory (P0)
  ✓ src/payment/webhook.ts              [P2]  reason: direct task relevance
  ✓ src/payment/idempotency.ts          [P2]  reason: direct task relevance
  ✓ memory/decision/idempotency-key.md  [P1]  reason: project memory (accepted_decision)
  …

Excluded (61):
  × src/camera/stream.ts           — no task relevance
  × docs/architecture-overview.md  — duplicate of docs/architecture.md
  × .ctxd/sessions/session-2.md    — low priority

76k tokens of candidate context became 4.5k — and every inclusion and exclusion has a stated reason. Not compression: selection you can audit.

Storage is cheap. Model context is expensive. Every token sent to a model should have a reason to exist.

Principles

• Local-first. No cloud, no accounts, no telemetry. Your repository, memory and decisions never leave your machine.

• Deterministic. No embeddings, no LLM in the core. The same inputs produce byte-identical output, which is why it can be benchmarked.

• Auditable. Every context build produces a receipt. Nothing is included without a reason, and nothing is dropped silently.

• Provider-independent. Claude, Cursor and whatever comes next are workers. They are replaceable; your memory is not.

• Honest. Token counts are labelled estimates, never dollar figures. Unavailable signals read as zero rather than being invented.

Install

Requires Node.js 24+.

npm install -g @ctxd/cli
ctxd doctor

doctor verifies Node, SQLite, FTS5, storage, config, the database, logging, Git and offline capability. Every check actually runs — none reports success without executing.

From source

For contributors, or to run an unreleased change. Requires pnpm as well.

git clone https://github.com/g0GobliN/ctxd.git
cd ctxd
pnpm install
pnpm build:all      # core packages, then the interface bundle

node packages/cli/dist/index.js doctor

pnpm build alone builds the core packages; build:all also builds the interface. React and Vite are build-time only — nothing remote is ever fetched at runtime.

To put ctxd on your PATH from a source checkout:

# a) link it globally (needs "pnpm setup" once, to create the global bin dir)
pnpm --filter @ctxd/cli link --global

# b) or add an alias to your shell profile
alias ctxd="node /absolute/path/to/ctxd/packages/cli/dist/index.js"

On Windows, where alias does not exist, put a ctxd.cmd containing node "C:/path/to/ctxd/packages/cli/dist/index.js" %* in a directory already on PATH.

Quickstart

# 1. Register your project. Detection reads real manifest files,
#    never guesses from directory names.
ctxd init --dir .

# 2. Build context for a task
ctxd context --task "Fix the webhook retry logic" --budget 10000

# 3. Record what a future session could not infer from the code
ctxd memory add --type DECISION --source accepted_decision \
  --title "Retry with exponential backoff" \
  --content "Fixed intervals caused a thundering herd under load."

# 4. Keep work across interruptions
ctxd session start --worker claude
ctxd checkpoint --next "Fix the 409 path then rerun tests"
ctxd resume
ctxd handoff --to cursor

Connect an AI worker

claude mcp add ctxd -- ctxd mcp --dir /path/to/project

Claude Code and Cursor then share one project memory — neither owns it. The agent asks ctxd for context instead of reading your whole repository, and records what it learns.

Crucially: a worker cannot overwrite what you told it. Agent conclusions are stored as worker_statement with visible confidence. If one contradicts a rule you stated, the write is refused and the conflict reported.

How it works

task ──► signals ──► candidates ──► dedup ──► rank ──► budget ──► receipt
                          ▲                              │
                     memory + git                  compression

Two rules do most of the work:

• Leftover budget is not a reason to send a file. An item with no connection to the task is excluded even when there is room. This is why a 10k budget often returns 4.5k.

• Search decides what is relevant; it does not decide what is mandatory. Every P0 rule is retrieved whether or not it shares vocabulary with the task.

Deep dive: docs/context-engine.md.

The other direction

The context firewall controls what goes to a worker. The Diff Firewall inspects what comes back.

$ ctxd diff --task "Change the webhook retry limit from 3 to 5"

CHANGE RECEIPT 4f1c9a02

Changed:   3 files
Added:     241 lines      Removed: 118 lines

Semantic:        6 lines
Formatting-only: 312 lines (1 file)
Unrelated:       1 file
Dependency:      1 file

Assessment: NEEDS_REVIEW  (risk: high)
Change efficiency score: 0.41 — a focus measure, not a correctness score

Why:
  · SMALL TASK / LARGE CHANGE MISMATCH
      expected about 2 file(s) and 20 changed line(s); got 3 file(s),
      +241/−118 (6 semantic)
  · src/camera/stream.ts shares no vocabulary with the task
  · package.json added a dependency the task did not ask for

Six lines of real change inside 359 lines of diff — and it says which is which.

It never edits, reverts or rejects anything. A large diff is not wrong by itself; sometimes the task needs one. The firewall makes the shape of a change visible so a person can decide.

ctxd verify then runs the project's own checks — never reporting a check as passed unless it actually ran. When one fails, it builds a correction context: the failed command, the error, and the code it points at. Not the original context. The worker already has that.

See it

ctxd ui     # http://127.0.0.1:4317

A local interface over the same receipts: the context inspector showing why each file was included or excluded, the change inspector, project memory, tasks and Git state.

It binds loopback only, refuses a non-loopback Host or Origin, and requires a local token for anything that writes. It is a viewer, not a second brain — everything it shows is available from the CLI.

Deep dives: docs/ui.md · docs/api.md.

Deep dive: docs/diff-firewall.md · docs/verification.md.

Commands

Every command supports --help.

Project status

Early but real. Phases 1–10 of the specification are built, tested and documented — 655 tests, including seven golden benchmarks that turn 77k–151k token fixture repositories into 2k–6k while keeping everything each task needs, and three change benchmarks covering the output firewall.

2.0 — the graph control centre — is complete. UI-0 through UI-12: the event log and live stream, real worker state, the interactive graph home screen, the activity stream, the Change Firewall panel, the token monitor, verification freshness, cross-worker handoff, and the Tauri desktop shell. Eleven panels ship, worker monitor and settings among them.

ctxd ui        # the interface in a browser
ctxd desktop   # the same interface in a native window

The desktop shell is verified on Windows 11 and not yet built on macOS or Linux. There is no installer yet — see desktop.md.

Nothing in this repository calls a network service or an AI model.

APIs may change before 1.0.

Documentation

Contributing

Contributions are very welcome — especially benchmark scenarios, which is how retrieval quality gets measured rather than argued about.

Start with CONTRIBUTING.md.

pnpm install && pnpm build && pnpm test

By participating you agree to the Code of Conduct. Security issues: see SECURITY.md.

Licence

MIT © the ctxd authors.