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

> Discover the Headroom learn command's failure mining process. Understand how it analyzes agent logs and writes corrective rules to CLAUDE.md for improved coding.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-20

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md) for Claude Code, [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md) for Codex, [`GEMINI.md`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/writer.py), the system creates a fenced section inside the target file:

```markdown
<!-- 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`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md) remains editable while receiving automated updates.

The generated entries follow concrete patterns, such as:

```markdown

### File Path Corrections

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

```

These entries are written directly into [`CLAUDE.md`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py).

**Dry-run mode** (preview changes without writing):

```bash
headroom learn

```

**Apply learnings** (writes to [`CLAUDE.md`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md)):

```bash
headroom learn --apply

```

**Target a specific project**:

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

```

**Process all discovered projects**:

```bash
headroom learn --all --apply

```

**Select a specific LLM backend**:

```bash
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`](https://github.com/chopratejas/headroom/blob/main/headroom/cli/learn.py)**: CLI entry point that parses options and orchestrates the scanning → analysis → writing pipeline.
- **[`headroom/learn/plugins/claude.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/plugins/claude.py)**: Plugin implementation for Claude Code, defining log locations and [`CLAUDE.md`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md) update logic.
- **[`headroom/learn/analyzer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/learn/analyzer.py)**: Shared LLM invocation layer that extracts patterns from failure-success pairs.
- **[`headroom/learn/writer.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md) (or [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md)/[`GEMINI.md`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/CLAUDE.md), [`AGENTS.md`](https://github.com/chopratejas/headroom/blob/main/AGENTS.md), and [`GEMINI.md`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.