# ZeroContext

A `CLAUDE.md` or `.cursorrules` file loads everything you have ever written into every
message. Your Postgres conventions are resident in the window while you're editing a
React component. The rules never get smaller, and the agent reads all of them every turn.

ZeroContext is a local MCP server that serves rules the other way round: the agent asks
for what matches the file it's working on, and gets only that slice.

```bash
npx zerocontext init      # writes an MCP config pointing at the local server
npx zerocontext serve     # stdio MCP server, serves matching rules on request
npx zerocontext analyze   # measures what your current rule file costs per message
```

## The honest version of the pitch

This is a **window-scoping** win, not a cheaper bill. A preloaded `CLAUDE.md` gets
prompt-cached, and an A/B I ran early on found just-in-time came out cost-neutral to
slightly *higher* end to end. Saying otherwise would have made a better headline and
been false.

What you get is relevance: a smaller, sharper window, and rules that are actually about
the code in front of the agent. That's worth having on its own, and I'd rather the README
say so than quietly imply savings that aren't there.

## `analyze`

The command I use most is the one that doesn't change anything. `npx zerocontext analyze`
reads whatever rule file a repo already has and prints how many rule tokens it keeps
resident in every single message, then what the just-in-time path would keep instead:
a fixed MCP overhead, the tool call, and one rule slice.

It also prints the break-even point, and if your rules are small enough that ZeroContext
would be a net loss, it says that rather than inflating the number. A tool that can only
report good news isn't a measurement.

The tokenizer is `o200k_base` via `gpt-tokenizer`, labelled as a proxy for Claude's count
rather than presented as exact — roughly ±10–15%. The percentage is the part that holds; the
absolute number is an estimate and is labelled as one.

## How the serving works

The server inspects the working directory on startup and detects the stack from project
signals, additively. A Next.js app is also React and TypeScript, so all three rule sets
activate, and each file gets only the slices whose globs match it. `drizzle.config.*` or
`drizzle-orm` alongside a Postgres driver activates the Node + Postgres + Drizzle set.

It's **agent-pulled, not an editor hook**. That's a deliberate limitation. Claude Code is
a terminal agent — there is no "current file changed" event for a server to listen to, so
chasing one would mean shipping an IDE extension and pretending the terminal case works.
Serving rules when the agent asks is the mechanism that actually works today.

The other thing it removes is the file itself. Rules live in the server, and the only
thing in your repo is one gitignored `.mcp.json` pointer — no rule file per AI tool.

## Stack

Node.js, TypeScript, the Model Context Protocol SDK, published on npm. Runs locally over
stdio; nothing leaves the machine.
