Headroom Learn Command: How Failure Mining Writes to CLAUDE.md

The headroom learn command is a CLI tool that scans coding agent session logs, analyzes failure-success pairs using an LLM, and generates corrective rules written to CLAUDE.md via marker-delimited blocks.

The headroom learn command in the chopratejas/headroom repository provides offline failure learning for AI coding assistants like Claude Code, Codex, and Gemini. It transforms historical session data into project-specific corrective rules that prevent repeated mistakes. This process, known as failure mining, automatically updates your agent's context files with actionable patterns extracted from past errors.

What Is the Headroom Learn Command?

The headroom learn command implements a pipeline that converts raw agent logs into structured corrections. According to the source code in headroom/cli/learn.py, the command follows a four-stage workflow.

Plugin Discovery

Each supported agent provides a plugin (e.g., ClaudeCodePlugin in headroom/learn/plugins/claude.py) that defines session file locations such as ~/.claude/projects/*.jsonl.

Log Scanning

The scanner reads historic logs and extracts "failed" tool calls paired with subsequent "succeeded" calls that resolved the issue.

LLM Analysis

The shared analyzer (headroom/learn/analyzer.py) invokes configured LLMs like Claude Sonnet, GPT-4o, or Gemini Flash to infer underlying patterns—whether wrong file paths, missing flags, or permission issues.

Context File Writing

The writer component updates agent-native context files (CLAUDE.md for Claude Code, AGENTS.md for Codex, GEMINI.md for Gemini) with the inferred rules.

How Failure Mining Writes to CLAUDE.md

The failure mining process uses marker-delimited blocks to safely manage automated content injection. As implemented in headroom/learn/writer.py, the system creates a fenced section inside the target file:

<!-- headroom:learn:start -->

## Headroom Learned Patterns

*Auto-generated by `headroom learn` — do not edit manually*
…
<!-- headroom:learn:end -->

On subsequent executions, only the content between these markers is replaced, preserving any user-written sections outside the boundaries. This ensures that CLAUDE.md remains editable while receiving automated updates.

The generated entries follow concrete patterns, such as:

### File Path Corrections

- `axion-common/src/.../AxionSparkConstants.scala`
  → actually at `axion-spark-common/src/.../AxionSparkConstants.scala`

These entries are written directly into CLAUDE.md and are subsequently referenced by the agent during future sessions to prevent recurrence of the same errors.

CLI Usage Examples

The headroom learn command supports multiple operational modes through command-line options defined in headroom/cli/learn.py.

Dry-run mode (preview changes without writing):

headroom learn

Apply learnings (writes to CLAUDE.md):

headroom learn --apply

Target a specific project:

headroom learn --project ~/my-project --apply

Process all discovered projects:

headroom learn --all --apply

Select a specific LLM backend:

headroom learn --model gpt-4o
headroom learn --model gemini-cli

Key Implementation Files

The failure mining architecture spans several critical modules:

• headroom/cli/learn.py: CLI entry point that parses options and orchestrates the scanning → analysis → writing pipeline.
• headroom/learn/plugins/claude.py: Plugin implementation for Claude Code, defining log locations and CLAUDE.md update logic.
• headroom/learn/analyzer.py: Shared LLM invocation layer that extracts patterns from failure-success pairs.
• headroom/learn/writer.py: Handles marker-based insertion and replacement in context files.

Summary

• The headroom learn command provides offline failure learning for Claude Code, Codex, and Gemini agents.
• Failure mining extracts patterns from historic session logs using LLM analysis.
• Generated rules are written to CLAUDE.md (or AGENTS.md/GEMINI.md) using marker-delimited blocks that preserve manual edits.
• The --apply flag commits changes, while --model selects alternative LLM backends.
• Implementation spans headroom/cli/learn.py, plugin modules, and the shared writer component.

Frequently Asked Questions

What file types does the Headroom learn command support?

The headroom learn command processes agent-specific session logs (typically .jsonl files) stored in directories like ~/.claude/projects/. It outputs to markdown context files including CLAUDE.md, AGENTS.md, and GEMINI.md depending on the configured plugin.

How does the command prevent overwriting manual edits in CLAUDE.md?

The writer implementation in headroom/learn/writer.py uses HTML comment markers (<!-- headroom:learn:start --> and <!-- headroom:learn:end -->) to delineate auto-generated content. During updates, only the text between these markers is replaced, leaving user-written sections intact.

Can I use Headroom learn with coding agents other than Claude Code?

Yes. The plugin architecture in headroom/learn/plugins/ supports multiple agents including Codex and Gemini. Each plugin defines its own log scanning logic and target context file (e.g., GEMINI.md for Gemini), allowing the same failure mining pipeline to work across different AI assistants.

What LLM models are compatible with the analyzer?

The analyzer in headroom/learn/analyzer.py supports various backends including Claude Sonnet, GPT-4o, and Gemini Flash. You can specify your preferred model using the --model flag, with options like gpt-4o or gemini-cli available depending on your API keys or local installations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}