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: fix env var discrepancies across markdown files
pratikbin42b1cd24de62
diff --git a/RUST_DEV.md b/RUST_DEV.mdindex 68a6ea67f..45b9c78e7 100644--- a/RUST_DEV.md+++ b/RUST_DEV.md@@ -67,7 +67,7 @@ curl -s http://127.0.0.1:8787/healthz/upstream # => 200 if upstream reachable```bash# 1. Move the Python proxy to a private port (e.g. 8788)-HEADROOM_BIND=127.0.0.1:8788 python -m headroom.proxy & # or your existing launcher+HEADROOM_HOST=127.0.0.1 HEADROOM_PORT=8788 python -m headroom.proxy & # or your existing launcher# 2. Run the Rust proxy on the previously-public port (8787) pointing at it./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 &diff --git a/docs/spec/005-integrations.md b/docs/spec/005-integrations.mdindex 7fe9e2bb2..0763e5e1b 100644--- a/docs/spec/005-integrations.md+++ b/docs/spec/005-integrations.md@@ -44,8 +44,7 @@ class ClaudeLearnPlugin(LearnPlugin, ConversationScanner):**Configuration:**```bash-HEADROOM_LEARN_CLAUDE_ENABLED=true-HEADROOM_LEARN_CLAUDE_SESSION_MODES=auto,learn,disabled+HEADROOM_LEARN_CLI=claude```---@@ -85,7 +84,7 @@ class CodexLearnPlugin(LearnPlugin, ConversationScanner):**Configuration:**```bash-HEADROOM_LEARN_CODEX_ENABLED=true+HEADROOM_LEARN_CLI=codex```---@@ -125,7 +124,7 @@ class GeminiLearnPlugin(LearnPlugin, ConversationScanner):**Configuration:**```bash-HEADROOM_LEARN_GEMINI_ENABLED=true+HEADROOM_LEARN_CLI=gemini```---diff --git a/docs/spec/008-capabilities.md b/docs/spec/008-capabilities.mdindex acbc573e8..fabf11305 100644--- a/docs/spec/008-capabilities.md+++ b/docs/spec/008-capabilities.md@@ -58,9 +58,8 @@ class CCRConfig:**Configuration:**```bash-HEADROOM_SUMMARY_ENABLED=true-HEADROOM_SUMMARY_THRESHOLD=5000 # tokens-HEADROOM_SUMMARY_RATIO=0.3 # compress to 30%+# Note: HEADROOM_SUMMARY_* env vars are not yet implemented.+# Summary compression is currently configured programmatically only.```**Behavior:**diff --git a/docs/spec/010-data.md b/docs/spec/010-data.mdindex ca2aa5892..c1a75234d 100644--- a/docs/spec/010-data.md+++ b/docs/spec/010-data.md@@ -93,9 +93,8 @@ CREATE TABLE compression_store (| Variable | Default | Description ||----------|---------|-------------|-| `HEADROOM_DB_PATH` | `~/.headroom/` | Base path for databases |-| `HEADROOM_DB_URL` | - | External database URL (overrides default) |-| `HEADROOM_CACHE_PATH` | `~/.headroom/cache/` | Compression cache location |+| `HEADROOM_WORKSPACE_DIR` | `~/.headroom` | Workspace root; all DBs live under this directory |+| `HEADROOM_CONFIG_DIR` | `~/.headroom/config` | Config root (read-mostly: models.json, per-plugin config) |### Cache@@ -158,12 +157,12 @@ curl http://localhost:8787/statstar -czf headroom-backup.tar.gz ~/.headroom/```-### External Database+### Storage Location-Set `HEADROOM_DB_URL` for external storage:+Relocate all storage by setting the workspace root:```bash-export HEADROOM_DB_URL=postgresql://user:pass@host:5432/headroom+export HEADROOM_WORKSPACE_DIR=/mnt/state```---diff --git a/docs/spec/013-disaster-recovery.md b/docs/spec/013-disaster-recovery.mdindex 335482bf7..dcc5f6a08 100644--- a/docs/spec/013-disaster-recovery.md+++ b/docs/spec/013-disaster-recovery.md@@ -51,10 +51,7 @@ sqlite3 ~/.headroom/headroom_memory.db ".backup /tmp/headroom_incremental.db"### External Storage-```bash-export HEADROOM_DB_URL=postgresql://user:pass@host:5432/headroom-export HEADROOM_CACHE_BACKEND=redis-```+> **Note:** External PostgreSQL/Redis storage is not yet implemented. Headroom uses SQLite at `~/.headroom/` (configurable via `HEADROOM_WORKSPACE_DIR`). The `HEADROOM_DB_URL` and `HEADROOM_CACHE_BACKEND` vars do not exist.---diff --git a/docs/spec/016-observability.md b/docs/spec/016-observability.mdindex d9f797819..fae8b5fcf 100644--- a/docs/spec/016-observability.md+++ b/docs/spec/016-observability.md@@ -36,11 +36,14 @@ scrape_configs:OpenTelemetry tracing support.-**Configuration:**+**Configuration (Langfuse):**```bash-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317-OTEL_SERVICE_NAME=headroom-HEADROOM_TRACING_ENABLED=true+LANGFUSE_PUBLIC_KEY=pk-lf-...+LANGFUSE_SECRET_KEY=sk-lf-...+HEADROOM_LANGFUSE_ENABLED=1+# Optional: override endpoint and service name+# LANGFUSE_BASE_URL=https://cloud.langfuse.com+# HEADROOM_LANGFUSE_SERVICE_NAME=headroom```**Spans:**@@ -78,8 +81,8 @@ HEADROOM_TRACING_ENABLED=true**Configuration:**```bash-HEADROOM_LOG_LEVEL=INFO-HEADROOM_LOG_FORMAT=json+# Logging level is controlled via the --log-level CLI flag (headroom proxy --log-level debug)+# or RUST_LOG env var for the Rust proxy. No HEADROOM_LOG_LEVEL env var exists.```Or in config:diff --git a/docs/spec/017-operations.md b/docs/spec/017-operations.mdindex 41f3c7a62..ec429ba10 100644--- a/docs/spec/017-operations.md+++ b/docs/spec/017-operations.md@@ -66,16 +66,13 @@ curl http://localhost:8787/readyz### Log Levels-Set via environment:+Set via CLI flag or `RUST_LOG` env var for the Rust proxy:```bash-HEADROOM_LOG_LEVEL=INFO-```+# Python proxy+headroom proxy --log-level debug-Or in config:-```yaml-logging:- level: INFO- format: json+# Rust proxy+RUST_LOG=debug headroom-proxy --upstream http://...```---diff --git a/examples/deployment/macos-launchagent/README.md b/examples/deployment/macos-launchagent/README.mdindex fa77796ea..37ea9bd8c 100644--- a/examples/deployment/macos-launchagent/README.md+++ b/examples/deployment/macos-launchagent/README.md@@ -9,7 +9,7 @@ This directory contains templates and scripts for running the headroom proxy ser./install.sh# Add shell integration to ~/.bashrc or ~/.zshrc-export HEADROOM_PROXY_PORT=8787+export HEADROOM_PORT=8787source /path/to/shell-integration.sh```diff --git a/wiki/configuration.md b/wiki/configuration.mdindex d5808f9d3..15c9a515c 100644--- a/wiki/configuration.md+++ b/wiki/configuration.md@@ -267,9 +267,6 @@ Some settings can be configured via environment variables:| Variable | Description | Default ||----------|-------------|---------|-| `HEADROOM_LOG_LEVEL` | Logging level | `INFO` |-| `HEADROOM_STORE_URL` | Database URL | temp directory |-| `HEADROOM_DEFAULT_MODE` | Default mode | `optimize` || `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | - || `HEADROOM_CONFIG_DIR` | Canonical config (read-mostly) root. Derives `models.json` and per-plugin config paths when set. | `~/.headroom/config` || `HEADROOM_WORKSPACE_DIR` | Canonical workspace (read-write state) root. Derives savings ledger, memory DB, logs, TOIN, subscription state, and more when set. | `~/.headroom` |diff --git a/wiki/macos-deployment.md b/wiki/macos-deployment.mdindex 5e7e34350..19a577ba9 100644--- a/wiki/macos-deployment.md+++ b/wiki/macos-deployment.md@@ -171,7 +171,7 @@ The default port is 8787. To use a custom port:1. Uninstall: `./uninstall.sh`2. Reinstall with new port: `./install.sh --port 9000`-3. Update shell integration: `export HEADROOM_PROXY_PORT=9000`+3. Update shell integration: `export HEADROOM_PORT=9000`### Log Location@@ -195,7 +195,7 @@ Configure additional options in the plist `EnvironmentVariables` section:<key>EnvironmentVariables</key><dict><!-- Required: Proxy port -->- <key>HEADROOM_PROXY_PORT</key>+ <key>HEADROOM_PORT</key><string>8787</string><!-- Optional: API key (or set in shell) -->@@ -235,7 +235,7 @@ Add to `~/.bashrc` (bash) or `~/.zshrc` (zsh):```bash# Configure port (optional, defaults to 8787)-export HEADROOM_PROXY_PORT=8787+export HEADROOM_PORT=8787# Source shell integrationsource /path/to/headroom/examples/deployment/macos-launchagent/shell-integration.sh@@ -518,7 +518,7 @@ This will:# Remove shell integration from ~/.bashrc or ~/.zshrc# Delete or comment out:-# export HEADROOM_PROXY_PORT=8787+# export HEADROOM_PORT=8787# source .../shell-integration.sh```