<div align="center">

<img src="img/logo.png" alt="ctxd" width="64" />

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.

</div>

---

<p align="center"> <img src="img/overview.png" alt="ctxd context firewall — filter, rank, deduplicate, and compress project context for AI coding agents" width="900" /> </p>

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+ and pnpm.

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.

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

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

Stage	What it does
Signals	Normalise the task into terms and phrases
Candidates	Walk the repo honouring .gitignore/.ctxdignore; never index secrets
Retrieval	Pull in relevant project memory and current Git state
Dedup	Drop exact and near-duplicate copies (shingles + Jaccard > 0.90)
Rank	Weighted signals: keyword, path, file type, priority, recency, token cost
Budget	Select the set that fits; compress what doesn't; never truncate
Receipt	Explain every inclusion and exclusion

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

Command	Purpose
ctxd doctor	Verify the local environment
ctxd status	Version, storage, database, project, Git
ctxd init	Register and index a project
ctxd context	Build minimum useful context for a task
ctxd diff	Inspect a worker's changes before accepting them
ctxd verify	Run the project's own checks against those changes
ctxd search	Expand context incrementally
ctxd stats	What ctxd has kept out of the model's context
ctxd efficiency	The context reduction, on its own
ctxd memory	Record and search project knowledge
ctxd decision	Record and surface project decisions
ctxd bug	Record and surface previous bugs
ctxd explain	Attach a WHY note to a file or module
ctxd task	Track units of work
ctxd session	Track a working session
ctxd checkpoint	Record where the work stands
ctxd handoff	Everything another worker needs
ctxd resume	What was I doing?
ctxd ui	Serve the local API for the ctxd interface
ctxd mcp	Run the MCP server

Every command supports --help.

Project status

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

Phase	Status
1 · Foundation	✅
1.5 · Context engine	✅
2 · Project intelligence	✅
3 · Persistent memory	✅
4 · Production context firewall	✅
5 · MCP + worker integration	✅
6 · Tasks, sessions, checkpoints, handoffs	✅
7 · Verification + Diff Firewall	✅
8 · Local API + web UI	✅
9 · Optimisation + benchmarks	✅
10 · Optional local AI	🚧 next

Not built yet: the worker monitor and settings panels. Nothing in this repository calls a network service or an AI model.

APIs may change before 1.0.

Documentation

Document	Contents
architecture.md	Packages, dependencies, schema
context-engine.md	Ranking, selection, compression, receipts
diff-firewall.md	Change surface, over-edit detection, Change Receipts
verification.md	Verification, architecture drift, correction context
memory.md	Memory types, authority order, FTS5 search
work.md	Tasks, sessions, checkpoints, handoffs
api.md	The local HTTP API and its security model
ui.md	The interface, how it is served, and its dependencies
mcp.md	The MCP tool surface
benchmarks.md	Benchmark scenarios, results, performance targets
development.md	Building, testing, conventions
plan.md	The full specification

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.