Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/headroomlabs-ai/headroom/llms.txt

Use this file to discover all available pages before exploring further.

Every coding agent session leaves behind a trail of failed tool calls — wrong file paths, broken commands, stubborn retries. headroom learn reads those transcripts, finds what the model did to fix each failure, and writes specific corrections to your project’s memory files so the same mistakes don’t happen next session.

​
Quick Start

# Preview recommendations for the current project (dry run — no changes)
headroom learn

# Write recommendations to CLAUDE.local.md
headroom learn --apply

# Analyze a specific project
headroom learn --project ~/my-project --apply

# Analyze all projects at once
headroom learn --all --apply

# Write to the team-shared file instead of the personal local one
headroom learn --apply --target CLAUDE.md
headroom learn runs entirely offline after the initial scan — it needs an LLM only for the analysis step. Set --model gpt-4o or --model gemini/gemini-flash-latest to use a non-default model.

​
Success Correlation — The Core Innovation

Most failure loggers just count errors. headroom learn maps each failure to the fix that worked:
StepExample
FailedRead axion-formats/src/main/java/.../FirstClassEntity.java
Then succeededRead axion-scala-common/src/main/scala/.../FirstClassEntity.scala
Learning written`FirstClassEntity` is at `axion-scala-common/`, not `axion-formats/`
This produces specific, actionable corrections — not generic advice.

​
Categories of Learnings

Environment Facts

Which runtime commands work vs. fail in this project’s environment.

File Path Corrections

Exact locations for files the model keeps guessing wrong.

Search Scope

Which directories to search (narrow paths fail, broader ones work).

Command Patterns

How commands should — and should not — be run.

​
Example output written to CLAUDE.local.md

### Environment
- **Python**: use `uv run python` (not `python3` — modules not available outside venv)

### File Path Corrections
- `axion-common/src/.../AxionSparkConstants.scala`
  -> actually at `axion-spark-common/src/.../AxionSparkConstants.scala`

### Search Scope
- Don't search `axion-model/` -> use `axion/` (the repo root)

### 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)

### Known Large Files
- `proxy/server.py` (~8000 lines) — always use offset/limit with Read

​
Output Targets

By default, learnings go to CLAUDE.local.md in your project root — Claude Code’s personal memory file, which should be gitignored so machine-specific facts don’t pollute the team repo.
TargetWhen to use
CLAUDE.local.mdDefault. Personal, gitignored. Machine-specific paths and tool-discovery byproducts.
CLAUDE.mdTeam-shared. Pass --target CLAUDE.md to opt in.
AGENTS.mdCodex / OpenAI Agents SDK projects.
GEMINI.mdGemini CLI projects.
Any custom pathPass --target <path> (relative to project root, or absolute).
If an older Headroom version already wrote a learned-patterns block into your team-shared CLAUDE.md, the next headroom learn --apply moves it into CLAUDE.local.md and prints a warning so you can review the diff before committing.
Headroom manages a clearly-delimited section — your existing file content is always preserved: 
<!-- headroom:learn:start -->
## Headroom Learned Patterns
*Auto-generated by `headroom learn` — do not edit manually*
...
<!-- headroom:learn:end -->

​
Supported Agents

Built-in plugins ship for the three most common coding agents:

claude

Claude Code — reads ~/.claude/projects/*.jsonl transcripts.

codex

Codex CLI — shares memory with Claude.

gemini

Gemini CLI — writes to GEMINI.md.
External agents register via a pip entry point: 
# pyproject.toml of your plugin package
[project.entry-points."headroom.learn_plugin"]
mycursor = "my_package:CursorLearnPlugin"
Pass --agent <name> to target a specific agent, or leave it as auto (the default) to scan all detected agents.

​
Verbosity Learning

headroom learn --verbosity mines behavioral signals from your past sessions — interrupts, fast-skips, echo ratio — to automatically pick the right terseness level for the output shaper: 
# Preview what it found (dry run)
headroom learn --verbosity

# Persist the level and enable it on a running proxy
headroom learn --verbosity --apply
Verbosity levels range from 1 (skip ceremony) to 4 (caveman/fragments). When --apply is used, Headroom hot-enables the output shaper on the running proxy via POST /admin/runtime-env — no restart required.
Add --llm-judge to let an LLM override the heuristic level with a one-sentence rationale. Requires an API key.

​
CLI Reference

headroom learn [OPTIONS]

Options:
  --project PATH     Project directory to analyze (default: current directory)
  --all              Analyze all discovered projects
  --apply            Write recommendations (default: dry-run)
  --target TEXT      Context file to write to, Claude Code only
                     (default: CLAUDE.local.md)
  --agent TEXT       Agent to analyze: auto, claude, codex, gemini,
                     or any registered plugin
  --model TEXT       LLM model for analysis
                     (e.g. claude-sonnet-4-6, gpt-4o, gemini/gemini-flash-latest)
  -j, --workers INT  Parallel workers for session scanning (default: auto)
  --main-only        Only scan top-level sessions, skip subagent transcripts
  --verbosity        Learn preferred output verbosity instead of analyzing failures
  --llm-judge        With --verbosity: let an LLM override the heuristic level

​
Real-World Results

Tested on 67,583 tool calls across 23 projects:
MetricValue
Failure rate7.5% (5,066 failures)
Corrections extracted164 per project (avg)
Path corrections22 (axion project)
Search scope corrections24 (axion project)
Command patterns learned5 (axion project)

​
Architecture

headroom learn uses an adapter pattern so new agent systems can be added without touching the analysis logic:
  • Scanners read tool-specific log formats and produce normalized ToolCall sequences.
  • Analyzers work on ToolCall data — the same analysis logic for any agent.
  • Writers output to tool-specific context injection mechanisms (e.g., CLAUDE.md, AGENTS.md).
To add support for a new agent, implement a Scanner for its log format and a Writer for its context file. The analyzers stay the same.

Build docs developers (and LLMs) love

Get started for freeTalk to us