``` ██████╗ ███████╗████████╗████████╗███████╗██████╗ ██████╗████████╗██╗ ██╗ ██╔══██╗██╔════╝╚══██╔══╝╚══██╔══╝██╔════╝██╔══██╗ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██████╔╝█████╗ ██║ ██║ █████╗ ██████╔╝ ██║ ██║ ╚███╔╝ ██╔══██╗██╔══╝ ██║ ██║ ██╔══╝ ██╔══██╗ ██║ ██║ ██╔██╗ ██████╔╝███████╗ ██║ ██║ ███████╗██║ ██║ ╚██████╗ ██║ ██╔╝ ██╗ ╚═════╝ ╚══════╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ The Intelligence Layer for AI Coding ```

The Intelligence Layer for AI Coding

Shell Hook + Context Server · 25 tools · 90+ patterns · Single Rust binary

Website · Install · How It Works · Tools · Patterns · Changelog · Discord

---
> **better-ctx** reduces LLM token consumption by **up to 99%** through three complementary strategies in a single binary — making AI coding faster, cheaper, and more effective.
## ⚡ What It Does ``` Without better-ctx: With better-ctx: LLM ──"read auth.ts"──▶ Editor ──▶ File LLM ──"ctx_read auth.ts"──▶ better-ctx ──▶ File ▲ │ ▲ │ │ │ ~2,000 tokens (full file) │ │ ~13 tokens (cached) │ cache+hash │ └──────────────────────────────────┘ └────── (compressed) ───────┴────────────┘ LLM ──"git status"──▶ Shell ──▶ git LLM ──"git status"──▶ better-ctx ──▶ git ▲ │ ▲ │ │ │ ~800 tokens (raw output) │ │ ~150 tokens │ compress │ └─────────────────────────────────┘ └────── (filtered) ─────┴──────────────┘ ``` | Strategy | How | Impact | |:---|:---|:---| | **Shell Hook** | Transparently compresses CLI output (90+ patterns) before it reaches the LLM | **60-95%** savings | | **Context Server** | 25 MCP tools for cached reads, mode selection, deltas, dedup, memory | **74-99%** savings | | **AI Tool Hooks** | One-command integration via `better-ctx init --agent ` | Works everywhere |
## 🎯 Token Savings — Real Numbers | Operation | Freq | Without | With better-ctx | Saved | |:---|:---:|---:|---:|:---:| | File reads (cached) | 15× | 30,000 | 195 | **99%** | | File reads (map mode) | 10× | 20,000 | 2,000 | **90%** | | ls / find | 8× | 6,400 | 1,280 | **80%** | | git status/log/diff | 10× | 8,000 | 2,400 | **70%** | | grep / rg | 5× | 8,000 | 2,400 | **70%** | | cargo/npm build | 5× | 5,000 | 1,000 | **80%** | | Test runners | 4× | 10,000 | 1,000 | **90%** | | curl (JSON) | 3× | 1,500 | 165 | **89%** | | docker ps/build | 3× | 900 | 180 | **80%** | | **Session total** | | **~89,800** | **~10,620** | **88%** | > Based on typical Cursor/Claude Code sessions with medium TypeScript/Rust projects. Cached re-reads cost ~13 tokens.
## 🚀 Get Started (60 seconds) ```bash # 1. Install (pick one) curl -fsSL https://betterctx.com/install.sh | sh # universal, no Rust needed brew tap jadzeino/betterctx-client && brew install better-ctx # macOS / Linux npm install -g better-ctx-bin # Node.js cargo install better-ctx # Rust # 2. Setup (auto-configures shell + ALL detected editors) better-ctx setup # 3. Verify better-ctx doctor ```

Troubleshooting

| Problem | Fix | |:---|:---| | Commands broken? | Run `better-ctx-off` (fixes current session) | | Permanent fix? | Run `better-ctx uninstall` (removes all hooks) | | Binary missing? | Aliases auto-fallback to original commands (safe) | | Manual fix? | Edit `~/.zshrc`, remove the `better-ctx shell hook` block | | Preview changes? | `better-ctx init --global --dry-run` | | Diagnose? | `better-ctx doctor` | better-ctx creates a backup of your shell config before modifying it (`~/.zshrc.better-ctx.bak`).

Supported editors (auto-detected by better-ctx setup)

| Editor | Method | Status | |:---|:---|:---:| | **Cursor** | MCP + hooks + rules | ✅ Auto | | **Claude Code** | MCP + PreToolUse hooks + rules | ✅ Auto | | **GitHub Copilot** | MCP | ✅ Auto | | **Windsurf** | MCP + rules | ✅ Auto | | **VS Code** | MCP + rules | ✅ Auto | | **Zed** | Context Server (settings.json) | ✅ Auto | | **Codex CLI** | config.toml + AGENTS.md | ✅ Auto | | **Gemini CLI** | MCP + hooks + rules | ✅ Auto | | **OpenCode** | MCP + rules | ✅ Auto | | **Pi** | pi-better-ctx npm package | ✅ Auto | | **Qwen Code** | MCP + rules | ✅ Auto | | **Trae** | MCP + rules | ✅ Auto | | **Amazon Q Developer** | MCP + rules | ✅ Auto | | **JetBrains IDEs** | MCP + rules | ✅ Auto | | **Google Antigravity** | MCP + rules | ✅ Auto | | **Cline / Roo Code** | MCP + rules | ✅ Auto | | **Aider** | Shell hook + rules | ✅ Auto | | **Amp** | Shell hook + rules | ✅ Auto | | **AWS Kiro** | MCP + rules | ✅ Auto | | **Continue** | MCP + rules | ✅ Auto |

## 🧠 Three Intelligence Protocols

### CEP **Cognitive Efficiency Protocol** Adaptive LLM communication with compliance scoring (0-100), task complexity classification, quality scoring, auto-validation pipeline. *Measurable efficiency gains*

### CCP **Context Continuity Protocol** Cross-session memory that persists tasks, findings, decisions across chats. LITM-aware positioning for optimal attention placement. *-99.2% cold-start tokens*

### TDD **Token Dense Dialect** Symbol shorthand (`λ` `§` `∂` `τ` `ε`) and ROI-based identifier mapping for compact LLM communication. *8-25% extra savings*

## 🛠 25 Intelligent Tools ### Core | Tool | Purpose | Savings | |:---|:---|:---:| | `ctx_read` | File reads — 7 modes + `lines:N-M`, caching, `fresh=true` | 74-99% | | `ctx_multi_read` | Multiple file reads in one round trip | 74-99% | | `ctx_tree` | Directory listings (ls, find, Glob) | 34-60% | | `ctx_shell` | Shell commands with 90+ compression patterns | 60-90% | | `ctx_search` | Code search (Grep) | 50-80% | | `ctx_compress` | Context checkpoint for long conversations | 90-99% | ### Intelligence | Tool | What it does | |:---|:---| | `ctx_smart_read` | Adaptive mode — auto-picks full/map/signatures/diff based on file type and cache | | `ctx_delta` | Incremental updates — only sends changed hunks via Myers diff | | `ctx_dedup` | Cross-file deduplication — finds shared imports and boilerplate | | `ctx_fill` | Priority-based context filling — maximizes info within a token budget | | `ctx_intent` | Semantic intent detection — classifies queries and auto-loads files | | `ctx_response` | Response compression — removes filler, applies TDD | | `ctx_context` | Multi-turn session overview — tracks what the LLM already knows | | `ctx_graph` | Project intelligence graph — dependency analysis + related file discovery | | `ctx_discover` | Shell history analysis — finds missed compression opportunities | ### Memory & Multi-Agent | Tool | What it does | |:---|:---| | `ctx_session` | Cross-session memory — persist task, findings, decisions across chats | | `ctx_knowledge` | Persistent project knowledge — remember facts, recall by query/category | | `ctx_agent` | Multi-agent sharing — register agents, post/read scratchpad, coordinate sessions | | `ctx_wrapped` | Shareable savings report — "Spotify Wrapped" for your tokens | ### Analysis | Tool | What it does | |:---|:---| | `ctx_benchmark` | Single-file or project-wide benchmark with preservation scores | | `ctx_metrics` | Session statistics with USD cost estimates | | `ctx_analyze` | Shannon entropy analysis + mode recommendation | | `ctx_cache` | Cache management: status, clear, invalidate |
## 📖 ctx_read Modes | Mode | When to use | Token cost | |:---|:---|:---| | `full` | Files you will edit (cached re-reads ≈ 13 tokens) | 100% first, ~0% cached | | `map` | Understanding a file — deps + exports + API | ~5-15% | | `signatures` | API surface with more detail than map | ~10-20% | | `diff` | Re-reading files that changed | changed lines only | | `aggressive` | Large files with boilerplate | ~30-50% | | `entropy` | Repetitive patterns (Shannon + Jaccard filtering) | ~20-40% | | `lines:N-M` | Specific ranges (e.g. `lines:10-50,80-90`) | proportional |
## 🔌 Shell Hook Patterns (90+) Pattern-based compression for **90+ commands** across **34 categories**:

View all 34 categories

| Category | Commands | Savings | |:---|:---|:---:| | **Git** (19) | status, log, diff, add, commit, push, pull, fetch, clone, branch, checkout, switch, merge, stash, tag, reset, remote, blame, cherry-pick | 70-95% | | **Docker** (10) | build, ps, images, logs, compose ps/up/down, exec, network, volume, inspect | 70-90% | | **npm/pnpm/yarn** (6) | install, test, run, list, outdated, audit | 70-90% | | **Cargo** (3) | build, test, clippy | 80% | | **GitHub CLI** (9) | pr list/view/create/merge, issue list/view/create, run list/view | 60-80% | | **Kubernetes** (8) | get pods/services/deployments, logs, describe, apply, delete, exec, top, rollout | 60-85% | | **Python** (7) | pip install/list/outdated/uninstall/check, ruff check/format | 60-80% | | **Ruby** (4) | rubocop, bundle install/update, rake test, rails test | 60-85% | | **Linters** (4) | eslint, biome, prettier, stylelint | 60-70% | | **Build Tools** (3) | tsc, next build, vite build | 60-80% | | **Test Runners** (8) | jest, vitest, pytest, go test, playwright, cypress, rspec, minitest | 90% | | **Terraform** | init, plan, apply, destroy, validate, fmt, state, import, workspace | 60-85% | | **Make** | make targets, parallel jobs, dry-run | 60-80% | | **Maven / Gradle** | compile, test, package, install, clean, dependency trees | 60-85% | | **.NET** | dotnet build, test, restore, run, publish, pack | 60-85% | | **Flutter / Dart** | flutter pub, analyze, test, build; dart pub, analyze, test | 60-85% | | **Poetry / uv** | install, sync, lock, run, add, remove; uv pip/sync/run | 60-85% | | **AWS** (7) | s3, ec2, lambda, cloudformation, ecs, logs, sts | 60-80% | | **Databases** (2) | psql, mysql/mariadb | 50-80% | | **Prisma** (6) | generate, migrate, db push/pull, format, validate | 70-85% | | **Helm** (5) | list, install, upgrade, status, template | 60-80% | | **Bun** (3) | test, install, build | 60-85% | | **Deno** (5) | test, lint, check, fmt, task | 60-85% | | **Swift** (3) | test, build, package resolve | 60-80% | | **Zig** (2) | test, build | 60-80% | | **CMake** (3) | configure, build, ctest | 60-80% | | **Ansible** (2) | playbook recap, task summary | 60-80% | | **Composer** (3) | install, update, outdated | 60-80% | | **Mix** (5) | test, deps, compile, format, credo/dialyzer | 60-80% | | **Bazel** (3) | test, build, query | 60-80% | | **systemd** (2) | systemctl, journalctl | 50-80% | | **Utils** (5) | curl, grep/rg, find, ls, wget | 50-89% | | **Data** (3) | env (filtered), JSON schema extraction, log dedup | 50-80% |

After `better-ctx init --global`, **23 commands** are transparently compressed via shell aliases: ``` git · npm · pnpm · yarn · cargo · docker · docker-compose · kubectl · k gh · pip · pip3 · ruff · go · golangci-lint · eslint · prettier · tsc ls · find · grep · curl · wget ```
## 👀 Examples

Directory listing — 239 → 46 tokens (-81%)

``` # ls -la src/ # better-ctx -c "ls -la src/" total 96 core/ drwxr-xr-x 4 user staff 128 ... tools/ drwxr-xr-x 11 user staff 352 ... cli.rs 9.0K -rw-r--r-- 1 user staff 9182 ... main.rs 4.0K -rw-r--r-- 1 user staff 4096 ... server.rs 11.9K ... shell.rs 5.2K 4 files, 2 dirs [better-ctx: 239→46 tok, -81%] ```

File reading (map mode) — 2,078 → ~30 tokens (-99%)

``` # Full read (284 lines, ~2078 tokens) # better-ctx read stats.rs -m map (~30 tokens) use serde::{Deserialize, Serialize}; stats.rs [284L] use std::collections::HashMap; deps: serde:: use std::path::PathBuf; exports: StatsStore, load, save, record, format_gain API: #[derive(Serialize, Deserialize)] cl ⊛ StatsStore pub struct StatsStore { fn ⊛ load() → StatsStore pub total_commands: u64, fn ⊛ save(store:&StatsStore) pub total_input_tokens: u64, fn ⊛ record(command:s, input_tokens:n, output_tokens:n) ... fn ⊛ format_gain() → String (284 more lines) [2078 tok saved (100%)] ```

curl (JSON) — 127 → 14 tokens (-89%)

``` # curl -s httpbin.org/json # better-ctx -c "curl -s httpbin.org/json" { JSON (428 bytes): "slideshow": { { "author": "Yours Truly", slideshow: {4K} "date": "date of publication", } "slides": [ [better-ctx: 127→14 tok, -89%] { "title": "Wake up to WonderWidgets!", ... ```

Visual terminal dashboard

``` $ better-ctx gain ◆ better-ctx Token Savings Dashboard ──────────────────────────────────────────────────────── 1.7M 76.8% 520 $33.71 tokens saved compression commands USD saved Cost Breakdown (@ $2.50/M input, $10/M output) ──────────────────────────────────────────────────────── Without better-ctx $44.75 ($5.79 input + $38.96 output) With better-ctx $11.04 ($1.76 input + $9.28 output) Saved $33.71 ($4.03 input + $29.68 output) Top Commands ──────────────────────────────────────────────────────── curl 48x ████████████████████ 728.1K 97% git commit 34x ██████████▎ 375.2K 50% ctx_read 103x █▌ 59.1K 38% ... +33 more commands better-ctx v2.14.2 | betterctx.com | better-ctx dashboard ```

## 🔬 Scientific Compression Engine Built on information theory and attention modeling (v2.6): | Feature | What it does | Impact | |:---|:---|:---:| | **Adaptive Entropy** | Per-language BPE entropy + Jaccard thresholds with Kolmogorov adjustment | 10-25% | | **Attention Model** | Heuristic U-curve positional weighting + structural importance scoring | ↑ comprehension | | **TF-IDF Codebook** | Cross-file pattern dedup via cosine similarity | 5-15% | | **Feedback Loop** | Learns optimal thresholds per language/file type across sessions | auto-improving | | **Info Bottleneck** | Entropy + task-relevance filtering (Tishby et al., 2000) | 20-40% | | **ctx_overview** | Multi-resolution project map with graph-based relevance tiers | 90%+ |
## 🌳 tree-sitter Signature Engine AST-based signature extraction for **18 languages**: TypeScript, JavaScript, Rust, Python, Go, Java, C, C++, Ruby, C#, Kotlin, Swift, PHP, Bash, Dart, Scala, Elixir, Zig. | Capability | Regex (old) | tree-sitter | |:---|:---:|:---:| | Multi-line signatures | ✗ | ✓ | | Arrow functions | ✗ | ✓ | | Nested classes/methods | Heuristic | AST scope | | Languages | 4 | **14** | Build without tree-sitter for a smaller binary (~5.7 MB vs ~17 MB): ```bash cargo install better-ctx --no-default-features ```
## 📊 CLI Commands

Shell Hook

```bash better-ctx -c "git status" # Execute + compress output better-ctx exec "cargo build" # Same as -c better-ctx shell # Interactive REPL with compression ```

File Operations

```bash better-ctx read file.rs # Full content (structured header) better-ctx read file.rs -m map # Deps + API signatures (~10% tokens) better-ctx read file.rs -m signatures # Function/class signatures only better-ctx read file.rs -m aggressive # Syntax-stripped (~40% tokens) better-ctx read file.rs -m entropy # Shannon entropy filtered (~30%) better-ctx read file.rs -m "lines:10-50,80-90" # Specific line ranges better-ctx diff file1.rs file2.rs # Compressed file diff better-ctx grep "pattern" src/ # Grouped search results better-ctx find "*.rs" src/ # Compact find results better-ctx ls src/ # Token-optimized directory listing better-ctx deps . # Project dependencies summary ```

Setup & Analytics

```bash better-ctx setup # One-command setup: shell + editors + verify better-ctx init --global # Install 23 shell aliases better-ctx init --agent claude # Claude Code hook better-ctx init --agent cursor # Cursor hooks.json better-ctx init --agent gemini # Gemini CLI hook better-ctx init --agent codex # Codex AGENTS.md better-ctx init --agent windsurf # .windsurfrules better-ctx init --agent cline # .clinerules better-ctx init --agent pi # Pi Coding Agent extension better-ctx gain # Visual terminal dashboard better-ctx gain --live # Live auto-updating dashboard better-ctx gain --graph # ASCII chart (30 days) better-ctx gain --daily # Day-by-day breakdown better-ctx gain --json # Raw JSON export better-ctx dashboard # Web dashboard (localhost:3333) better-ctx cheatsheet # Quick reference better-ctx discover # Find uncompressed commands better-ctx doctor # Diagnostics better-ctx update # Self-update better-ctx wrapped # Shareable savings report better-ctx benchmark run # Real project benchmark better-ctx benchmark report # Markdown report ```

Multi-Agent Launcher

```bash lctx # Auto-detect agent, current dir lctx --agent claude # Launch Claude Code with better-ctx lctx --agent cursor # Configure Cursor lctx --agent gemini # Launch Gemini CLI lctx /path/to/project "prompt" # Project + prompt lctx --scan-only # Build project graph only ```

## ⚙️ Editor Configuration > **`better-ctx setup` handles this automatically.** Manual config below is only needed for edge cases.

Cursor

`~/.cursor/mcp.json`: ```json { "mcpServers": { "better-ctx": { "command": "better-ctx" } } } ```

GitHub Copilot

`.github/copilot/mcp.json`: ```json { "servers": { "better-ctx": { "command": "better-ctx" } } } ```

Claude Code

```bash claude mcp add better-ctx better-ctx ```

Windsurf

`~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "better-ctx": { "command": "better-ctx" } } } ``` > If tools don't load, use the full path (e.g., `/Users/you/.cargo/bin/better-ctx`). Windsurf spawns MCP servers with a minimal PATH.

Zed

`~/.config/zed/settings.json`: ```json { "context_servers": { "better-ctx": { "source": "custom", "command": "better-ctx", "args": [], "env": {} } } } ```

OpenAI Codex

`~/.codex/config.toml`: ```toml [mcp_servers.better-ctx] command = "better-ctx" args = [] ```

Gemini CLI

`~/.gemini/settings/mcp.json`: ```json { "mcpServers": { "better-ctx": { "command": "better-ctx" } } } ```

Pi Coding Agent

```bash better-ctx init --agent pi # Or: pi install npm:pi-better-ctx ``` Pi's `bash`, `read`, `grep`, `find`, and `ls` tools are automatically routed through better-ctx. Supports 55+ file extensions with auto mode selection.

OpenCode

`~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "better-ctx": { "type": "local", "command": ["better-ctx"], "enabled": true } } } ```

## 🏆 better-ctx vs RTK | Feature | RTK | better-ctx | |:---|:---:|:---:| | Architecture | Shell hook only | **Shell hook + MCP server** | | Process model | Spawns per command | **Persistent server** (no EAGAIN) | | CLI patterns | ~50 | **90+** | | File reading | Signatures only | **7 modes** (full, map, signatures, diff, aggressive, entropy, lines) | | File caching | ✗ | ✓ (re-reads ≈ 13 tokens) | | Signature engine | Regex (4 langs) | **tree-sitter AST (18 langs)** | | Dependency maps | ✗ | ✓ | | Context checkpoints | ✗ | ✓ | | Token counting | Estimated | **tiktoken-exact** | | Entropy analysis | ✗ | ✓ | | Cost tracking | ✗ | ✓ (USD estimates) | | TDD mode | ✗ | ✓ (8-25% extra) | | Thinking reduction | ✗ | ✓ (CRP v2) | | Cross-session memory | ✗ | ✓ (CCP) | | LITM positioning | ✗ | ✓ | | Multi-agent sharing | ✗ | ✓ | | Project knowledge store | ✗ | ✓ | | Web dashboard | ✗ | ✓ | | Savings reports | ✗ | ✓ (`wrapped`) | | Raw mode / bypass | ✓ | ✓ (`raw=true`, `--raw`, `better-ctx-raw`) | | User-defined filters | TOML rules | **TOML rules** (priority over builtins) | | Full output recovery | `tee` | ✓ (`tee_mode: always/failures/never`) | | Truncation warnings | ✗ | ✓ (transparent markers) | | ANSI auto-strip | ✗ | ✓ (pre-compression) | | Telemetry | **Default ON (PII)** | **Zero. None. Ever.** | | Editor support | 3 editors | **23 editors/tools** |
## 🔐 Privacy & Security better-ctx is **privacy-first by design**: - **Zero telemetry** — no data collection, no analytics, no phone-home, ever - **Zero network requests** — everything runs locally on your machine - **No PII exposure** — no hostnames, usernames, or project paths leave your system - **Fully auditable** — MIT-licensed, single Rust binary, no hidden dependencies See [SECURITY.md](SECURITY.md). > **Note on VirusTotal:** Rust binaries are frequently flagged by ML-based heuristic scanners. This is a [known issue](https://users.rust-lang.org/t/rust-programs-flagged-as-malware/49799). Build from source with `cargo install better-ctx` to verify.
## 🗑 Uninstall ```bash better-ctx init --global # See what was added, then remove from shell profile cargo uninstall better-ctx # Remove binary rm -rf ~/.better-ctx # Remove stats + config ```
## 🤝 Contributing Contributions welcome! Open an issue or PR on [GitHub](https://github.com/jadzeino/betterctx-client).

Discord · 𝕏 / Twitter · Buy me a coffee ☕

## 📄 License MIT — see [LICENSE](LICENSE).

_{Built with 🦀 Rust · Made in Switzerland 🇨🇭}