dont-burn.token

01 · What it does

The problem it solves

AI coding agents do not know which files matter, so they read whole files to find one function, re-read files they already opened, and pull in raw API responses padded with null fields. This adds four things to a project: behaviour rules in CLAUDE.md, a lazy-loaded skill index, a generated project map the agent reads instead of exploring, and a CLI that strips noise out of JSON, logs and diffs. The README states this cuts token use by 40–90% depending on session type. Everything is markdown plus the Python standard library, so there is nothing to install past Python.

02 · Setup

Before you start

• ✓Python 3.10 or newer — the scripts import only the standard library
• ✓Bash, for session/init.sh
• ✓An AI tool that reads markdown context files
• ✓No pip install step and no external packages

03 · Step by step

Getting it running

1. 01

   Generate a project map

   Point generate.py at the project the agent will work on. It walks 24 source extensions and writes an index of identity files, dependencies, a directory tree, entry points and exported symbols.

   $python3 snapshot/generate.py /path/to/your/project
2. 02

   Control where the snapshot lands

   With one argument the snapshot is written inside the toolkit clone, not inside your project. Pass a second path so your agent will actually read it.

   $python3 snapshot/generate.py /path/to/project /path/to/project/snapshot/project.md
3. 03

   Bootstrap the session

   init.sh regenerates the snapshot if source files are newer than it, then prints a brief with snapshot size, skill count and the load order for the agent.

   $bash session/init.sh /path/to/your/project
4. 04

   Paste the load-order prompt first

   init.sh prints a one-line prompt telling the agent which files to read and in what order, then stop. Paste it verbatim so context is loaded once instead of discovered.

5. 05

   Or let Claude Code pick the rules up on its own

   Claude Code reads a CLAUDE.md in the project root at session start, so copying that one file applies the response and tool-use rules with no prompt to paste.

   $cp CLAUDE.md /path/to/your/project/CLAUDE.md
6. 06

   Compress large tool output

   Pipe API responses, logs or diffs through compress.py. JSON mode drops null and empty fields and truncates long arrays; logs mode keeps signal lines; diff mode collapses unchanged hunks.

   $curl -s https://api.example.com/data | python3 session/compress.py --type json
7. 07

   Mine a finished session for repeat waste

   learn.py reads a .jsonl session log and flags preambles, repeated file reads and oversized outputs. The --distill run folds the top ten into an appendix in CLAUDE.md.

   $python3 session/learn.py session.jsonl && python3 session/learn.py --distill

04 · What you get

Capabilities

05 · Before you rely on it

Limitations, honestly

Every tool has edges. These are the ones that will cost you time if nobody tells you first.

• !generate.py writes inside the toolkit clone even when pointed at another project, unless you pass an explicit second path.
• !compress.py is lossy — it drops null fields with no marker and truncates arrays to 10 by default. Do not use it when the agent needs the complete payload.
• !On small JSON inputs it re-serializes with indentation and returns more text than it received; its own reduction figure goes negative.
• !The load order references session/corrections.md, which is gitignored and absent on a fresh clone until learn.py has run.
• !init.sh only checks 5 extensions for staleness while generate.py indexes 24, so Ruby, Java, PHP and Swift projects never auto-refresh.
• !Nothing runs automatically. The repo’s own docs state it does not intercept API calls and does not guarantee savings — the 40–90% range is its own claim.
• !No LICENSE, no tests and no CI.