{
  "markdown": "<!-- mcp-name: io.github.sseshachala/agent-booster -->\n# Agent Booster\n\nCut AI coding agent token costs 5–15x by routing only the code that matters.\n\nInstead of sending full source files to the model on every read, Agent Booster builds a symbol index of your codebase and returns only the functions and classes relevant to the current task.\n\n![Agent Booster demo — fewer tokens sent, lower cost, same result](assets/agent-booster-demo.gif)\n\n---\n\n## How it works\n\n```\nWithout Booster                    With Booster\n─────────────────                  ────────────────────────────\nRead executor.py                   smart_read executor.py + task\n→ 1,881 lines (~6k tokens)         → 3 matching functions (~200 tokens)\n```\n\nFive layers work together:\n\n| Layer | What it does |\n|---|---|\n| **Symbol index** | tree-sitter parses every `.py`, `.ts`, `.tsx`, `.js`, `.jsx` file, extracts functions/classes into SQLite |\n| **Vector embeddings** | sentence-transformers encodes each symbol for semantic search |\n| **Smart read** | given a file + task, runs per-file vector search and returns only matching symbol line ranges |\n| **MCP server** | exposes four tools over stdio — any MCP-compatible agent can call them |\n| **Platform init** | one command writes the right config for Claude Code, Cursor, Windsurf, or Codex |\n\n---\n\n## Installation\n\nRequires Python 3.10+.\n\n```bash\npip install agent-booster          # symbol index + MCP tools\npip install agent-booster[embed]   # + semantic vector search (recommended)\n```\n\n---\n\n## Quickstart\n\n**Step 1 — Wire up your AI tool**\n\n```bash\nbooster init claude     # Claude Code\nbooster init cursor     # Cursor\nbooster init windsurf   # Windsurf\nbooster init codex      # OpenAI Codex CLI\nbooster init all        # all four\n```\n\nEach command shows exactly what files will change, asks for confirmation, then writes them. Fully reversible:\n\n```bash\nbooster remove claude   # or cursor, windsurf, codex, all\n```\n\nExample — wiring up OpenAI Codex (`booster init codex` → `booster start` → `booster gain`):\n\n![Agent Booster with OpenAI Codex — init writes ~/.codex/config.json + AGENTS.md, start indexes, gain reports savings](assets/agent-booster-codex-demo.gif)\n\n> **Run once per project, not once per session.**\n> The hooks live in `.claude/settings.json` and `.mcp.json` at the project root.\n> Every Claude Code session opened in this directory — any terminal window, same machine — picks them up automatically.\n> No per-session setup needed.\n\n**Step 2 — Index your codebase**\n\nRun once from your project root. Re-run after large refactors.\n\n```bash\nbooster index && booster embed\n# Indexed 260 files, 1800 symbols.\n# Built embeddings for 1800 symbols.\n```\n\nThe index is stored at `.booster/` (gitignored). The index is shared across all sessions.\n\n**Step 3 — Restart your AI tool**\n\nThe `agent-booster` MCP server is now available in every session. Claude Code (and other tools) will use `smart_read` and `search_context` automatically on indexed files.\n\n**Step 4 — Track savings**\n\n```bash\nbooster gain\n```\n\n---\n\n## CLI reference\n\n### `booster init <platform>`\n\nWrites the MCP server config and rules file for the target platform. Asks for confirmation before making any changes.\n\n```bash\nbooster init claude     # .mcp.json + CLAUDE.md + .claude/settings.json hook\nbooster init cursor     # .cursor/mcp.json + .cursorrules\nbooster init windsurf   # ~/.windsurf/mcp.json + .windsurfrules\nbooster init codex      # ~/.codex/config.json + AGENTS.md\nbooster init all        # all four\n\nbooster init claude --yes   # skip confirmation (CI/scripts)\n```\n\n### `booster remove <platform>`\n\nCleanly undoes everything `init` wrote. No residue.\n\n```bash\nbooster remove claude\nbooster remove cursor\nbooster remove windsurf\nbooster remove codex\nbooster remove all\n```\n\n### `booster index`\n\nScans all `.py`, `.ts`, `.tsx`, `.js`, `.jsx` files from the current directory. Extracts functions, classes, methods, and interfaces into `.booster/symbols.db`. Skips `node_modules`, `.venv`, `__pycache__`, `.git`, `.booster`, `.next`, `dist`, `build`.\n\n```bash\nbooster index\n# Indexed 260 files, 1800 symbols.\n```\n\n### `booster embed`\n\nBuilds sentence-transformer vector embeddings for all indexed symbols. Required for semantic `search_context` calls. Uses `all-MiniLM-L6-v2` (local, no data leaves your machine).\n\n```bash\nbooster embed\n# Built embeddings for 1800 symbols.\n```\n\n### `booster search \"<query>\"`\n\nKeyword search across all indexed symbols. Returns file path, line number, kind, name, and signature.\n\n```bash\nbooster search \"guard install\"\n# apps/web/src/app/settings/modules/page.tsx:99  function handleInstall  function handleInstall() {\n```\n\n### `booster route \"<task>\"`\n\nRecommends `haiku`, `sonnet`, or `opus` based on task complexity — keyword signals, file count, and symbol count.\n\n```bash\nbooster route \"fix the guard SSE role check\"\n# haiku  (narrow task — 0 symbol(s) in 1 file)\n\nbooster route \"refactor the entire runtime compiler and DSL layer\"\n# opus  (matches complexity keywords)\n```\n\n### `booster serve`\n\nStarts the MCP server over stdio. Called automatically by Claude Code, Cursor, Windsurf, and Codex when configured via `booster init`. You rarely need to run this directly.\n\n### `booster gain`\n\nShows token savings from past `smart_read` calls — total reads, tokens served vs. tokens saved, savings rate, and top files by savings.\n\n```\nAgent Booster — Token Savings Report\n─────────────────────────────────────\nActive days:        3\nTotal reads:        47\nTokens served:      12,400\nTokens saved:       89,200\nSavings rate:       88%\n\nTop files by savings:\n  executor.py              18,400 tokens saved  (12 reads)\n  guard.py                 14,200 tokens saved  (8 reads)\n```\n\n---\n\n## MCP tools\n\nOnce `booster serve` is running, these four tools are available to the agent:\n\n### `get_symbols(file)`\n\nReturns all indexed symbols for a file — name, kind, line range, and signature. No file read required.\n\n```\nInput:  { \"file\": \"apps/api/app/runtime/executor.py\" }\nOutput: function run_workflow (lines 42-89): def run_workflow(...)\n        class WorkflowState (lines 91-140): class WorkflowState:\n```\n\n### `search_context(task)`\n\nSemantic vector search across all symbols in the index. Returns top 10 matches by cosine similarity. Falls back to keyword search if embeddings haven't been built.\n\n```\nInput:  { \"task\": \"guard install uninstall\" }\nOutput: apps/web/src/app/settings/modules/page.tsx:99 function handleInstall — function handleInstall() {\n        apps/web/src/components/guard/GuardNav.tsx:13 function GuardNav — function GuardNav() {\n        ...\n```\n\n### `smart_read(file, task)`\n\nRuns per-file vector search and returns only the source lines for matching symbols, with a header showing name and line range. If no symbols match, returns an explicit message so the model knows to fall back to a full Read rather than silently receiving the whole file.\n\n```\nInput:  { \"file\": \"apps/api/app/runtime/executor.py\", \"task\": \"execute output block\" }\nOutput: # function _execute_output (lines 1165-1210)\n        def _execute_output(block, state, credentials, ...):\n            ...\n```\n\n### `route_model(task, files?)`\n\nRecommends `haiku`, `sonnet`, or `opus` based on task complexity signals. If `files` is omitted, auto-detects via `search_context`.\n\n```\nInput:  { \"task\": \"fix the login redirect bug\" }\nOutput: { \"model\": \"haiku\", \"reason\": \"narrow task — 1 symbol in 1 file\" }\n```\n\n---\n\n## What `booster init claude` writes\n\n| File | Change |\n|---|---|\n| `.mcp.json` | Adds `agent-booster` to `mcpServers` |\n| `CLAUDE.md` | Appends booster usage rules block (sentinel markers) |\n| `.claude/settings.json` | Wires `PreToolUse` (Read + Grep) and `UserPromptSubmit` hooks |\n| `.claude/hooks/booster-gate.py` | **Blocks** `Read` on indexed files — forces `smart_read` |\n| `.claude/hooks/booster-grep-nudge.py` | **Nudges** semantic `Grep` patterns toward `search_context` |\n| `.claude/hooks/booster-route.py` | **Auto route_model** — recommends haiku/sonnet/opus on every user turn |\n\n`booster remove claude` removes all six, cleanly. No residue.\n\n---\n\n## Where it fits\n\nAgent Booster is the third layer in a three-layer token reduction stack:\n\n```\nLayer 3 — Agent Booster     AST+semantic routing, smart file reads\nLayer 2 — RTK               Token compression on CLI/git/build output\nLayer 1 — Prompt caching    Stable context reuse (native to Claude Code + API)\n```\n\nEach layer is independent and addable separately.\n\n---\n\n## Common questions\n\n**Does it work if I open a second terminal?**\nYes. The hooks are wired into `.claude/settings.json` and `.mcp.json` in your project root — not inside a specific terminal session. Any new Claude Code window you open in this project picks them up automatically.\n\n**Do I need to run `booster init` again after restarting my machine?**\nNo. `booster init` writes files to disk once. They persist across restarts and across sessions. The only time you re-run it is if you delete those files or switch to a new project.\n\n**Do teammates need to run `booster init` too?**\nYes — once per developer, once per project. If you commit `.mcp.json` and `.claude/settings.json` to the repo, teammates get the hooks when they clone. They still need to run `pip install agent-booster[embed]` and `booster index && booster embed` locally, since the symbol index is gitignored.\n\n**Can I undo it completely?**\nYes. `booster remove claude` removes all six files and cleans the settings entries. No residue.\n\n## Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-booster\": {\n      \"command\": \"booster\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nRun `booster index && booster embed` once from your project root before starting Claude Desktop. No env vars required.\n\n---\n\n## Project layout\n\n```\ntools/booster/\n├── README.md\n├── pyproject.toml\n└── booster/\n    ├── cli.py          # click commands: index, embed, search, serve, init, remove, route, gain\n    ├── indexer.py      # tree-sitter parser + SQLite symbol store + vector search\n    ├── retriever.py    # smart_read: per-file vector search → relevant line slice\n    ├── mcp_server.py   # MCP server: get_symbols, search_context, smart_read, route_model\n    └── stats.py        # token savings tracking (booster gain)\n```\n",
  "bytes": 10398,
  "sha": "b52360af917580e46c3a3587fcf9904edebf0ca5dfe5325bdc82659265638964",
  "repo_slug": "sseshachala/agent-booster",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sseshachala_agent_booster_23e74c7b/readme"
}