Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Headroom Learn
Offline failure learning for coding agents. Analyzes past conversations, finds what went wrong, correlates it with what eventually worked, and writes specific project-level learnings that prevent the same mistakes next session.
Quick Start
# See recommendations for current project (dry-run, no changes)
headroom learn
# Write recommendations to CLAUDE.local.md (gitignored, personal default)
headroom learn --apply
# Write to the shared team file instead
headroom learn --apply --target CLAUDE.md
# Analyze a specific project
headroom learn --project ~/my-project --apply
# Analyze all projects
headroom learn --all --apply
How It Works
Past Sessions → Plugin → Analyzer → Writer → Agent-native context file
│ │ │
│ │ └─ Writes marker-delimited sections
│ │ (replaced on re-run, not duplicated)
│ │
│ └─ LLM-based analysis: finds failure patterns,
│ success correlations, and actionable rules
│
└─ Plugin reads agent-specific logs:
• Claude Code: ~/.claude/projects/*.jsonl
• Codex: ~/.codex/sessions/*.json
• Gemini CLI: ~/.gemini/tmp/*/chats/session-*.json
Success Correlation
The core innovation. Instead of cataloging failures ("Read failed 5 times"), Headroom finds what the model did to fix each failure:
- Failed:
Read axion-formats/src/main/java/.../FirstClassEntity.java - Then succeeded:
Read axion-scala-common/src/main/scala/.../FirstClassEntity.scala - Learning: "
FirstClassEntityis ataxion-scala-common/, notaxion-formats/"
This produces specific, actionable corrections — not generic advice.
What It Learns
1. Environment Facts → CLAUDE.md
Which runtime commands work vs fail.
### Environment
- **Python**: use `uv run python` (not `python3` — modules not available outside venv)
2. File Path Corrections → CLAUDE.md
Wrong paths the model keeps guessing, with the correct locations.
### File Path Corrections
- `axion-common/src/.../AxionSparkConstants.scala`
→ actually at `axion-spark-common/src/.../AxionSparkConstants.scala`
3. Search Scope → CLAUDE.md
Which directories to search in (narrow paths fail, broader ones work).
### Search Scope
- Don't search `axion-model/` → use `axion/` (the repo root)
4. Command Patterns → CLAUDE.md
How commands should (and shouldn't) be run.
### Command Patterns
- **user_prefers_manual**: User rejected gradle 18 times — show the command, don't execute
- **python_runtime**: Use `uv run python` not `python3` (ModuleNotFoundError)
5. Known Large Files → CLAUDE.md
Files that need offset/limit with Read.
### Known Large Files
- `proxy/server.py` (~8000 lines) — always use offset/limit
6. Retry Prevention → MEMORY.md
Specific suggestions derived from actual corrections.
7. Permission Notes → MEMORY.md
Commands repeatedly rejected — model should suggest them to the user instead.
Where Learnings Go
| Pattern | Claude Code | Codex | Gemini CLI |
|---|---|---|---|
| Environment, paths, commands | CLAUDE.local.md (default) or CLAUDE.md (with --target CLAUDE.md) |
AGENTS.md | GEMINI.md |
| Retry patterns, permissions | MEMORY.md | instructions.md | GEMINI.md |
Output files are agent-native: Claude Code writes to CLAUDE.local.md by default (gitignored, personal); pass --target CLAUDE.md for the shared team file. Codex uses AGENTS.md, Gemini uses GEMINI.md. The same learnings, written to the format each agent reads.
Marker-Based Updates
Headroom manages a clearly-delimited section in each file:
<!-- headroom:learn:start -->
## Headroom Learned Patterns
*Auto-generated by `headroom learn` — do not edit manually*
...
<!-- headroom:learn:end -->
On re-run, only the content between markers is replaced. Your existing file content is preserved.
Architecture (Plugin System)
Headroom Learn uses a plugin architecture where each agent is a self-contained plugin:
Plugin Registry (auto-discovered)
├── ClaudeCodePlugin → Analyzer (LLM) → ClaudeCodeWriter → CLAUDE.md / MEMORY.md
├── CodexPlugin → Analyzer (LLM) → CodexWriter → AGENTS.md / instructions.md
├── GeminiPlugin → Analyzer (LLM) → GeminiWriter → GEMINI.md
└── (your plugin) → Analyzer (LLM) → (your writer) → (your file)
Plugins bundle scanning, detection, and writing for one agent. Built-in plugins are auto-discovered from headroom.learn.plugins.*. External plugins register via the headroom.learn_plugin entry point.
The Analyzer is shared — it uses an LLM (Sonnet, GPT-4o, or Gemini Flash) to find patterns. Same analysis for any agent.
Adding Support for a New Agent
- Create
headroom/learn/plugins/myagent.py - Implement
LearnPlugin+ConversationScanner(scanner + writer + detection) - Add
plugin = MyAgentPlugin()at module scope - Done —
headroom learn --agent myagentworks automatically
Or install an external plugin: pip install headroom-learn-cursor (registers via entry point).
CLI Reference
headroom learn [OPTIONS]
Options:
--project PATH Project directory (default: current directory)
--all Analyze all discovered projects (mutually exclusive with --project)
--apply Write recommendations (default: dry-run)
--target TEXT Context file to write (default: CLAUDE.local.md for Claude Code)
--main-only Write only to the main context file, skip MEMORY.md
--agent [auto|claude|codex|gemini|grok|opencode]
Which agent to analyze (default: auto-detect)
--model TEXT LLM for analysis (default: auto from API keys or CLI)
--workers / -j INTEGER Parallel analysis workers (min 1, default: auto)
--verbosity Analyze verbosity level instead of failure patterns
--llm-judge Use an LLM to score verbosity quality (requires --verbosity)
Verbosity learning (--verbosity)
headroom learn --verbosity analyzes past sessions to infer the ideal output verbosity level for your project and writes a verbosity.json profile.
Important: the output shaper is off by default (HEADROOM_OUTPUT_SHAPER=1
turns it on; it is available on every rollout channel). Running --verbosity --apply will either:
- Hot-enable the output shaper on an eligible running proxy (
POST /admin/runtime-env), OR - Print instructions to set
HEADROOM_OUTPUT_SHAPER=1beforeheadroom wrap ...
A proxy in cache mode (the default) does not read verbosity.json: a level that
changes mid-conversation would bust the prompt cache, so it steers at its startup
level. On a cache-mode proxy --apply therefore also pins
HEADROOM_VERBOSITY_LEVEL to the learned level, and records the pin (port,
proxy pid, level) in verbosity_pin.json. A HEADROOM_VERBOSITY_LEVEL that is
already set is left alone, and --apply says so. The one exception is a pin that
record proves an earlier --apply set: the same proxy process still holding the
same raw value. That pin is replaced. A changed raw pin remains operator-owned
even if it clamps to the same effective level as the previous CLI pin.
To keep the shaper on across proxy restarts, export HEADROOM_OUTPUT_SHAPER=1 before starting the proxy, plus HEADROOM_VERBOSITY_LEVEL=<level> in cache mode.
Flag interactions:
--alland--projectare mutually exclusive--llm-judgerequires--verbosity--verbosity --all --applyis rejected (verbosity persists a single global level)
Supported Agents
| Agent | Scanner | Writer | Output Files |
|---|---|---|---|
| Claude Code | Reads ~/.claude/projects/*.jsonl |
ClaudeCodeWriter | CLAUDE.md, MEMORY.md |
| OpenAI Codex | Reads ~/.codex/sessions/*.json |
CodexWriter | AGENTS.md, instructions.md |
| Gemini CLI | Reads ~/.gemini/tmp/*/chats/session-*.json |
GeminiWriter | GEMINI.md |
| Grok CLI | Reads ~/.grok/sessions/<workspace>/<session-id>/updates.jsonl |
GrokWriter | GROK.md |
| OpenCode | Reads the OpenCode SQLite DB at ~/.local/share/opencode/opencode.db (or opencode-local.db; override with HEADROOM_OPENCODE_DB) |
CodexWriter (shared) | AGENTS.md, instructions.md |
LLM Backend Selection
headroom learn needs an LLM to analyze your sessions. It picks one automatically using this priority:
| Priority | Source | Example |
|---|---|---|
| 1 | --model flag |
headroom learn --model gpt-4o |
| 2 | API key env var | ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY |
| 3 | HEADROOM_LEARN_CLI env var |
export HEADROOM_LEARN_CLI=gemini |
| 4 | Auto-detect installed CLIs | Checks PATH for claude, gemini, codex |
Using without an API key
If you use Claude Code, Gemini CLI, or Codex via subscription (no raw API key), headroom learn can call them directly:
# Auto-detects claude in PATH — no API key needed
headroom learn
# Explicitly select a CLI backend
headroom learn --model gemini-cli
# Pin a CLI via environment variable
export HEADROOM_LEARN_CLI=codex
headroom learn
Valid values for HEADROOM_LEARN_CLI: claude, gemini, codex, agy.
agy (Antigravity CLI) is never auto-detected. It has no mode that starts a session without tools, so instructions embedded in analyzed session text could make it write files or run shell commands with your permissions. To use it anyway, opt in explicitly:
export HEADROOM_LEARN_CLI=agy
export HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1
headroom learn
Without HEADROOM_LEARN_ALLOW_UNSAFE_AGY=1, selecting agy (via HEADROOM_LEARN_CLI or --model agy-cli) fails before any analysis runs.
Real-World Results
Tested on 67,583 tool calls across 23 projects:
| Metric | Value |
|---|---|
| Failure rate | 7.5% (5,066 failures) |
| Corrections extracted | 164 per project (avg) |
| Specific path corrections | 22 (axion project) |
| Search scope corrections | 24 (axion project) |
| Command patterns learned | 5 (axion project) |
| Estimated preventable waste | ~27 MB across corpus |