Skip to content

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.

Merge remote-tracking branch 'origin/main' into feat/cli-llm-backend

Gyeonghun Parkda4b97112895
diff --cc docs/learn.md
index 45e762aeb,ce5b1b028..db531b569
--- a/docs/learn.md
+++ b/docs/learn.md
@@@ -142,42 -149,22 +149,51 @@@ Or install an external plugin: `pip ins
headroom learn [OPTIONS]
Options:
- --project PATH Project directory to analyze (default: current directory)
- --all Analyze all discovered projects
- --apply Write recommendations (default: dry-run)
- --model TEXT LLM model for analysis (default: auto-detected)
- --agent TEXT Which coding agent to analyze: auto, claude, codex, gemini
+ --project PATH Project directory (default: current directory)
+ --all Analyze all discovered projects
+ --apply Write recommendations (default: dry-run)
+ --agent [auto|claude|codex|gemini]
+ Which agent to analyze (default: auto-detect)
- --model TEXT LLM for analysis (default: auto from API keys)
++ --model TEXT LLM for analysis (default: auto from API keys or CLI)
```
+ ### 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 |
+
+## 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:
+
+```bash
+# 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`.
+
## Real-World Results
Tested on 67,583 tool calls across 23 projects: