How auto-learning works
You've run Headroom for days, worked your agent hard, and the learnings count still reads zero. Broken? Almost certainly not; it's the one part of Headroom designed to make you wait, and the wait is what makes the learnings worth having. This page covers what gets learned, where learnings end up, and exactly when your first one will appear.
What Headroom watches for
With auto-learning on (it's on by default), the local proxy watches your agent traffic for patterns worth remembering. Three kinds matter most: error recoveries (a command failed, and a slightly different one then worked); environment facts (which binaries, paths, and flags actually work on your machine); and preferences (corrections you keep giving the agent). Everything happens on your machine; traffic is never sent anywhere for analysis.
Where learnings end up
Confirmed patterns are written into the context files your agent already reads,
CLAUDE.md and MEMORY.md for Claude Code or the agent-native equivalents for Codex, inside
a clearly marked, auto-generated block. From then on your agent starts every session
already knowing that, say, plain python3 breaks on your machine and
/usr/bin/python3 works. That's tokens and failed round-trips you stop
paying for, every session, forever.
Why you see zero learnings at first
A pattern must be observed five times before Headroom saves it. That evidence gate is deliberate: writing every one-off hiccup into your CLAUDE.md would pollute the very context you're paying to slim down. The trade-off is patience: during your first sessions Headroom is accumulating evidence, not yet writing. The Optimize view shows how many patterns are currently under observation, so you can see learning is alive before the first one lands. Evidence survives restarts, so short sessions add up.
Manual scans, and turning it off
Alongside the live learner, the Optimize view can run a manual scan of a project's past sessions, useful for bootstrapping a project that already has weeks of history. And if you'd rather Headroom never touch your context files, the auto-learning toggle in the same view turns the live learner off entirely; manual scans remain available.
See also: beyond token savings for what learnings are worth over time, and troubleshooting if something else looks stuck.
See it on your own traffic: install Headroom and run a normal session.