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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Merge remote-tracking branch 'origin/main' into feat/cli-llm-backend
Gyeonghun Parkda4b97112895
diff --cc docs/learn.mdindex 45e762aeb,ce5b1b028..db531b569--- a/docs/learn.md+++ b/docs/learn.md@@@ -142,42 -149,22 +149,51 @@@ Or install an external plugin: `pip insheadroom 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 ResultsTested on 67,583 tool calls across 23 projects: