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
docs: add guide for using Headroom with OpenCode + DeepSeek (#2497)
suvenkatesh97565c6076efcc
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 6a45b0b4c..554918cc6 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -40,6 +40,7 @@"vscode-claude-code","vscode-copilot","opencode",+ "opencode-deepseek","grok-build","mcp","---Configuration---",diff --git a/docs/content/docs/opencode-deepseek.mdx b/docs/content/docs/opencode-deepseek.mdxnew file mode 100644index 000000000..83c21a982--- /dev/null+++ b/docs/content/docs/opencode-deepseek.mdx@@ -0,0 +1,233 @@+---+title: OpenCode + DeepSeek+description: Configure OpenCode to route DeepSeek traffic through the Headroom proxy for compression, output shaping, and savings visibility.+---++Save 20-60% on DeepSeek API costs with Headroom's context compression proxy.++## How it works++```+OpenCode → Headroom Proxy (:8787) → DeepSeek API+ ↑ compresses input+ + shapes output+```++The proxy sits between OpenCode and DeepSeek. It compresses tool outputs, logs,+and search results before they reach the model, then shapes responses to be+concise. DeepSeek's API is OpenAI-compatible — one flag and you're running.++---++## 1. Install Headroom++```bash+pip install headroom-ai+# or via uv:+uv tool install headroom-ai+```++You get SmartCrusher (structural compression), the proxy, output shaping, and+the MCP server — everything you need.++---++## 2. Get your DeepSeek API key++Sign up at [platform.deepseek.com](https://platform.deepseek.com) and generate+an API key.++Store it somewhere safe:+```bash+export DEEPSEEK_API_KEY="sk-your-deepseek-key-here"+```++---++## 3. Start the proxy++```bash+headroom proxy \+ --port 8787 \+ --openai-api-url https://api.deepseek.com/v1+```++The proxy auto-detects `api.deepseek.com` and labels itself "DeepSeek" on the+dashboard. Verify it's running:++```bash+curl http://127.0.0.1:8787/health+# → "status": "healthy"+```++To see which models the proxy exposes:+```bash+curl -s http://127.0.0.1:8787/v1/models \+ -H "Authorization: Bearer sk-your-key" | jq '.data[].id'+```++### With output shaping (optional)++Output shaping makes the model's responses shorter — fewer tokens, lower cost:++```bash+HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \+headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1+```++Verbosity levels:++| Level | Behavior |+|---|---|+| `1` | Skip preambles/postambles |+| `2` | + Don't restate code/file content already in context (**recommended**) |+| `3` | + Omit rationale unless asked |+| `4` | Maximum — fragments, zero fluff |++---++## 4. Configure OpenCode++**Note:** If you have an existing `~/.config/opencode/opencode.json` (for MCP+servers, etc.), merge the provider section into that file. Having both `.json`+and `.jsonc` in the same directory can cause conflicts.++Edit `~/.config/opencode/opencode.json`:++```jsonc+{+ "$schema": "https://opencode.ai/config.json",+ "model": "headroom/deepseek-v4-pro",+ "provider": {+ "headroom": {+ "npm": "@ai-sdk/openai-compatible",+ "name": "Headroom Proxy",+ "options": {+ "baseURL": "http://127.0.0.1:8787/v1",+ "apiKey": "sk-your-deepseek-key"+ },+ "models": {+ "deepseek-v4-pro": {+ "name": "DeepSeek V4 Pro",+ "limit": { "context": 1000000, "output": 384000 }+ },+ "deepseek-v4-flash": {+ "name": "DeepSeek V4 Flash",+ "limit": { "context": 1000000, "output": 384000 }+ }+ }+ }+ },+ "mcp": {+ "headroom": {+ "type": "local",+ "command": ["headroom", "mcp", "serve"],+ "enabled": true+ }+ }+}+```++**Important:** Only include model IDs that appear in the proxy's `/v1/models`+response. OpenCode validates config models against the proxy's model list.+The current DeepSeek model names are `deepseek-v4-pro` and `deepseek-v4-flash`.+`deepseek-chat` and `deepseek-reasoner` are deprecated compatibility aliases.++### Model comparison++| Model | Input / Output (per 1M) | Context | Max Output |+|---|---|---|---|+| `deepseek-v4-pro` | $0.435 / $0.87 | 1M | 384K |+| `deepseek-v4-flash` | $0.14 / $0.28 | 1M | 384K |++Both models support **thinking mode** for step-by-step reasoning (see below).++Switch models at any time with `/model` in OpenCode.++---++## 5. Start OpenCode++```bash+opencode+```++Run `/models` to confirm both DeepSeek models appear under "Headroom Proxy".+Select one with `/model deepseek-v4-flash` or `/model deepseek-v4-pro`.++---++## 6. Check savings++```bash+curl http://127.0.0.1:8787/stats | python3 -m json.tool | grep -A5 compression+```++Or open the dashboard at [http://127.0.0.1:8787/dashboard](http://127.0.0.1:8787/dashboard).++---++## Thinking mode (reasoning)++Both models support thinking mode natively, and DeepSeek enables it by default.+This replaces the deprecated `deepseek-reasoner` (R1) model.+See [DeepSeek's thinking mode docs](https://api-docs.deepseek.com/guides/thinking_mode)+for details on switching between thinking and non-thinking modes.++---++## Common issues++### "Authentication Fails" / Unauthorized++The `apiKey` in OpenCode's config is missing or wrong. OpenCode must send the+API key to the proxy, and the proxy forwards it to DeepSeek. Make sure+`"apiKey": "sk-..."` is set under `options`.++### Models don't appear under "Headroom Proxy"++1. Verify the proxy is running: `curl http://127.0.0.1:8787/health`+2. Check which models the proxy exposes: `curl -s http://127.0.0.1:8787/v1/models -H "Authorization: Bearer sk-your-key"`+3. Make sure your config model IDs match **exactly** what the proxy returns+4. Don't use both `opencode.json` and `opencode.jsonc` in the same config directory — use one file++### Models appear but requests fail++You ran `headroom wrap opencode`. That command replaces your config with Claude+and GPT models. **Do not use `headroom wrap`.** Configure OpenCode manually as+shown above, and launch OpenCode directly with `opencode`.++### "headroom" command not found++`uv tool install` puts binaries in `~/.local/bin/`. Add it to your PATH:++```bash+export PATH="$HOME/.local/bin:$PATH"+```++### Output shaping shows no savings++Output savings are measured against a learned baseline (it compares "what the+model actually emitted" vs "what it would have emitted unshaped"). After a few+sessions, run:++```bash+headroom learn --verbosity --apply+```++This builds the baseline, and `/stats` will show output savings numbers. The+shaper is active immediately — the numbers just need calibration.++---++## What's NOT in this guide++- **Claude or GPT models** — this setup uses DeepSeek exclusively+- **`headroom wrap`** — do not use it; it overrides the config+- **Deprecated model names** — `deepseek-chat` and `deepseek-reasoner` are+ compatibility aliases that will be deprecated on 2026-07-24; use+ `deepseek-v4-pro` and `deepseek-v4-flash` instead+- **Kompress (ML compression)** — requires extra dependencies; SmartCrusher+ handles the majority of use cases+- **Any code changes** — headroom ships full DeepSeek support natively+ (model tables, pricing, tokenizers, domain detection)