Markdown version of https://extraheadroom.com/docs/how-learning-works

# Project learnings

Headroom identifies reusable patterns in coding sessions and writes them to the instruction files your agent reads.

## What can be learned

- **Command corrections:** a failed command followed by a working alternative.
- **Environment details:** project paths, available tools, and supported command flags.
- **Repeated instructions:** project-specific preferences that the agent should apply in later sessions.

Saved instructions can reduce repeated exploration and failed commands. They do not guarantee that an agent will follow every instruction.

## Review project learnings

1. Open **Optimize** in Headroom and inspect the project's learning status.
2. Review saved learnings. The Auto-learning status shows the count of pending patterns when that information is available; it does not list each pending pattern.
3. Check the generated block in the project's agent instruction files. Current Claude scans write personal instructions to `CLAUDE.local.md` and Claude's project `MEMORY.md`; older versions wrote `CLAUDE.md`. Codex scans write to `~/.codex/AGENTS.md` and `~/.codex/instructions.md`.
4. In a new session, check whether the agent uses the recorded command or project detail.

## Scan existing sessions

In Optimize, use **Scan now** beside a Claude project or the ChatGPT Codex sessions row. Claude scans are per project; the Codex scan reads the available `~/.codex/sessions` history. Scans apply the resulting learnings automatically, so review the saved instructions afterward.

Claude scans require the `claude` CLI. Codex scans require the `codex` CLI signed in with your ChatGPT account. Optimize displays missing prerequisites and a **Re-check** control.

Manual scans use the agent CLI to analyze session content with its AI provider and can consume provider usage. They are separate from local input compression. Review saved instructions for outdated paths or commands.

## Why the count can remain zero

Session duration alone does not produce a learning. Headroom needs an eligible pattern and enough evidence to save it. A session without repeated corrections can produce no learnings.

Check that auto-learning is enabled, that the agent's requests reach Headroom, and that the intended project's session history is available. Check the pending-pattern count in Auto-learning before treating a zero count as a failure. If a manual scan also fails, follow [troubleshooting](/docs/troubleshooting#learnings).

## Control auto-learning

Use the auto-learning setting in Optimize to stop live learning. Manual scans remain available. Turning off live learning does not by itself remove instructions already written to project files; review those files separately if you want to remove existing learnings.