Stop your AI agent re-reading the whole project every session

The problem

Context does not survive between sessions. After a /clear, a /compact, or simply a new day, the agent has forgotten the shape of the project. Its instinct is to rebuild that picture by reading: a file here, a grep there, six files before it can answer a question it answered perfectly yesterday. That survey is pure overhead: tokens spent, wall-clock spent, and nothing built.

The fix: a STATE.md at the root

A STATE.md is one short file, at most eighty lines, that holds what a new session actually needs: what exists and its status, the decisions a future session would otherwise re-litigate, the last five changes, and what's still unfinished. A SessionStart hook injects it automatically after every clear and compact, so the agent starts oriented instead of blind. It answers from the file, and opens the real code only when it's time to edit it.

What it saved

In one controlled run per condition (the same project, the same two questions, two agents), so an indication rather than a benchmark, the one with a STATE.md used 12,052 tokens to the other's 50,882, a 76% cut, and reached the answer in 18.5 s against 70.6 s, 3.8× faster. Both answered both questions correctly. The agent without the file made ten tool calls and opened six files; the one with it made none.

The catch, honestly

On one question the agent without a STATE.md was more precise: it read the code and quoted exact constants with line numbers. So a good STATE.md carries pointers to where those values live, not the values themselves, which drift. The fallback is one targeted read, not a six-file survey, and that is the whole point.

Add it to your repo

We've packaged the hook, the template and an installer for Claude Code. They aren't public yet; this section will link them when they are.