Epistle
Codebase context for coding agents
It remembers the shape of a thing and forgets the flesh.
TypeScript · tree-sitter · MCP (stdio) · Node 18–22ISubjectWho it was for
A coding agent, a whole repository, and a context window that is never quite big enough.
IIPresenting symptomThe problem
The agent reads function bodies it never needed, runs out of window, and forgets the part that mattered.
IIIReconstructionWhat was really going on
Most of what an agent needs to find its way around a codebase is the shape: signatures, types, docstrings. Bodies are the bulk of the tokens and rarely the point.
Pasting a full pack into the conversation is its own failure. The agent pays for every line once, whether it ever looks at it or not.
IVInterventionWhat I built
- 01
A CLI and MCP server that packs a repository into one LLM-ready file.
- 02
--compresswalks real tree-sitter parse trees for TypeScript, JSX, Python, Go and Rust, so multi-line signatures, decorators and return types survive; other languages fall back to a line heuristic. - 03
Secrets are redacted by default.
--fitreports how the pack sits in each model's context window. - 04
Over MCP, big packs stay server-side. Four tools over stdio (
pack_codebase,pack_remote,read_output,grep_output) let the agent grep the pack instead of reading it.
VEvidenceResults
- −45%
- tokens, 64.7k → 35.8k
- 68-file Next.js repo, measured 26 Sep 2026
- ~260
- npm downloads a month
- npm API, 30-day window
- 70
- tests, CI on Node 18–22
- 4
- MCP tools over stdio
VILimitationsWhat it doesn't do
- The −45% is one measurement on one repository. The saving depends on how much of a codebase is function bodies.
- Compression drops implementations. When the agent needs a body it has to fetch it (
read_output,grep_output) or open the file. - The tree-sitter grammars are an optional ~55 MB dependency. Without them every language uses the line heuristic.
- Downloads are not users. ~260 a month says people install it, not that they keep it.
VIIExhibitsLinks
Email or form · reply within 24 h