{
  "markdown": "<!-- mcp-name: io.github.Mibayy/token-savior -->\n\n<div align=\"center\">\n\n# Token Savior\n\n> One MCP server. One profile. **97.9% on tsbench at -80% tokens.**\n> Structural code navigation, persistent memory, and Bash command rewriting for AI coding agents.\n\n[![PyPI](https://img.shields.io/pypi/v/token-savior-recall?color=orange&label=pypi)](https://pypi.org/project/token-savior-recall/)\n[![Benchmark](https://img.shields.io/badge/tsbench-97.9%25%20(188%2F192)-brightgreen)](https://mibayy.github.io/token-savior/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)\n[![CI](https://github.com/Mibayy/token-savior/actions/workflows/ci.yml/badge.svg)](https://github.com/Mibayy/token-savior/actions/workflows/ci.yml)\n\n**[mibayy.github.io/token-savior](https://mibayy.github.io/token-savior/)** -- project site + benchmark landing\nBenchmark source + fixtures: not currently published (see *Reproducing the score* below)\n\n---\n\n### Benchmark -- 96 real coding tasks (Claude Opus 4.7, May 2026)\n\n| | Plain Claude Code | With Token Savior |\n|---|---:|---:|\n| **Score** | 141 / 180 (78.3%) | **188 / 192 (97.9%)** |\n| **Active tokens / task** | 17 221 | **3 395** (-80%) |\n| **Wall time / task** | 110.6 s | **18.9 s** (-83%) |\n\nReproduces with the `optimized` profile (single env var). The harness that\nproduced these numbers is described below; its repository is not public at the\nmoment, so take the figures as reported rather than as independently verifiable.\n\n**A re-measurement was published here on 2026-08-09 and has been withdrawn on\n2026-08-10.** It reported new-token savings from a small replacement harness.\nThose numbers did not measure this server at all: across 143 benchmark\nsessions, **exactly one** called a Token Savior tool. The client running the\nharness had MCP deferred-tool loading enabled, so all 18 tools sat behind a\n`ToolSearch` lookup instead of appearing in the model's manifest. The model\nnever saw them and fell back to `Grep` and `Read` — 66 greps, 30 reads, one\nMCP call. What varied between the \"profiles\" was the size of the cached\nprefix, not what the agent did.\n\nThe lesson is worth more than the numbers were: **a benchmark of an MCP server\nmust assert that its tools were actually called.** Ours did not, so it happily\ncompared two identical agents. That assertion now exists in the harness.\n\nThe headline figures above therefore stand as reported and unverified, as\nstated in the previous paragraph. Re-measuring them properly is open work.\n\n</div>\n\n---\n\n## Who starred this repo?\n\n[![starscope](https://starscope.duckdns.org/badge/Mibayy/token-savior.svg)](https://starscope.duckdns.org/r/_Na5VtAKXt-H)\n\nOn June 30, 2026 GitHub restricted stargazer and watcher lists to repo admins and\ncollaborators, which broke every \"who starred my repo\" tool at once. I rebuilt one\nthat still works, precisely because it only reads repos you own or can push to:\n**[starscope](https://starscope.duckdns.org)** ranks the people who starred or\nforked your repo by influence, and surfaces their social accounts when their\nGitHub profile declares them.\n\nNumbers on this very repo, computed with it: 1,147 people, 27% with a public\nsocial account, and the most followed carries 18,922 followers. The named list is\nvisible to the repo owner and to nobody else — the [public\npage](https://starscope.duckdns.org/r/_Na5VtAKXt-H) shows aggregates only.\n\n---\n\n## What's new\n\nRelease notes live where they can't drift out of sync with the code:\n\n- [CHANGELOG.md](CHANGELOG.md) for the full history\n- [Releases](https://github.com/Mibayy/token-savior/releases) for the tagged builds\n- [PyPI](https://pypi.org/project/token-savior-recall/) for what `pip` will actually give you\n\n---\n\n## Quick start\n\n```bash\npip install \"token-savior-recall[mcp]\"\n```\n\nAdd to your MCP config (e.g. Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"token-savior-recall\": {\n      \"command\": \"/path/to/venv/bin/token-savior\",\n      \"env\": {\n        \"WORKSPACE_ROOTS\": \"/path/to/project1,/path/to/project2\",\n        \"TOKEN_SAVIOR_CLIENT\": \"claude-code\",\n        \"TOKEN_SAVIOR_PROFILE\": \"optimized\"\n      }\n    }\n  }\n}\n```\n\nThat's it. **`TOKEN_SAVIOR_PROFILE=optimized`** ships the Pareto-optimum\nconfig that wins tsbench. It bundles:\n\n- `tiny_plus` (15 hot tools manifest)\n- thin inputSchema (-44% manifest)\n- capture sandbox disabled\n- memory hooks gated for cross-project safety\n\nNo other tuning needed.\n\n---\n\n## Activation (Bash compaction + rewriting)\n\nBash compaction and the PreToolUse rewriter are opt-in. Two env vars and\none CLI call:\n\n```bash\nexport TS_BASH_COMPACT=1       # PostToolUse output compactors (34 of them)\nexport TS_BASH_REWRITE=1       # PreToolUse command rewriter (10 rules)\n\nts init --agent claude --yes   # auto-merge hooks into ~/.claude/settings.json\n```\n\n`ts init` is idempotent. It detects existing hook entries, dedups by\n`(matcher, command)`, prints a unified diff, and backs up `settings.json`\nto `.bak-YYYYMMDD-HHMMSS` (UTC) before writing. Supported agents:\n`claude`, `cursor`, `gemini`, `codex`, `openclaw`. Pass `--dry-run` to preview, or\n`--global` to write the user-level config.\n\nOptional audit log of every rewrite:\n\n```bash\nexport TS_BASH_REWRITE_LOG=$HOME/.local/state/token-savior/rewrites.jsonl\n```\n\n---\n\n## Compactor catalog (34)\n\n| Family | Compactors |\n|---|---|\n| git | `status`, `diff`, `log`, `push`/`pull`, `commit`, `add`, `fetch`, `checkout`, `branch`, `worktree list`, `stash list` |\n| gh | `run list`, `run view`, `pr diff`, `pr view`, `issue view`, `repo view` |\n| test/lint | `pytest`, `jest`, `vitest`, `eslint`, `biome`, `cargo test`, `cargo build`/`clippy`, `tsc` |\n| cloud | `kubectl get`, `kubectl logs`, `aws sts`, `aws ec2`, `aws lambda`, `aws logs`, `aws iam`, `aws dynamodb`, `aws s3` |\n| docker | `docker ps`, `docker logs` |\n| packaging | `npm/yarn/pnpm list`, `pip list`/`show` |\n| shell catch-alls | `grep`, `find`, `cat`, `curl` |\n\nEach compactor is a pure function (no I/O, no globals) returning a\ntoken-efficient rendering. The dispatcher returns `None` when no matcher\nfires, leaving the existing sandbox path untouched. Compound commands\n(`cd ... && cmd`) fall through to the last meaningful segment.\n\n> **These run in PostToolUse, so they do not shrink the current turn.** The\n> hook fires after the tool has returned; it can add context, not remove it.\n> The compact rendering is appended below the raw output, which stays. What\n> you gain is persistence: the full output goes to the capture sandbox and\n> outlives a context compaction. For an actual reduction of what reaches the\n> model, use the PreToolUse rewriter (`TS_BASH_REWRITE=1`) — it edits the\n> command before it runs.\n\n---\n\n## `ts_discover` -- find missed TS opportunities\n\nNew MCP tool that scans your Claude Code transcripts for patterns where\nTS tools would have been cheaper than what the agent actually did.\n\n```python\nts_discover()                       # active project, last 30 days\nts_discover(project=None)           # ALL transcript projects\nts_discover(format=\"adoption\")      # TS vs native ratio per session\nts_discover(format=\"adoption_json\") # same, JSON\n```\n\nFindings: Read->Grep->Read chains, sequential `find_symbol`, edits\nwithout `get_edit_context`, `memory_search` without `memory_index`,\nnative shell on code files. Args are pruned to load-bearing keys\n(PII-safe). Streams JSONL with mtime fast-skip.\n\n---\n\n## `ts init` CLI\n\n```bash\nts init --agent claude [--global] [--dry-run] [--yes]\nts init --agent cursor\nts init --agent gemini\nts init --agent codex\nts init --agent openclaw\n```\n\nDetects the target agent's settings location, deep-merges the Token\nSavior hook config (`PostToolUse` + `PreToolUse`), preserves existing\nhooks, dedups, prints a unified diff. Backs up to\n`settings.json.bak-YYYYMMDD-HHMMSS` (UTC). Re-running is a no-op.\n\n---\n\n## What it does\n\nClaude Code reads whole files to answer questions about three lines, and\nforgets everything the moment a session ends. Token Savior fixes both,\nplus a third axis: it bounds the noisy Bash output that bloats turn\nbudgets between code reads — by rewriting the command before it runs.\n\nIt indexes your codebase by symbol -- functions, classes, imports, call\ngraph -- so the model navigates by pointer instead of by `cat`. Measured\nreduction: 97% fewer chars injected across 170+ real sessions.\n\nOn top of that sits a persistent memory engine. Every decision, bugfix,\nconvention, guardrail and session rollup is stored in SQLite WAL + FTS5\n+ vector embeddings, ranked by Bayesian validity and ROI, and\nre-injected as a compact delta at the start of the next session.\n\nAnd on top of *that*, since v4.1, sit the Bash compactors and the\nPreToolUse rewriter. Bench numbers above.\n\n**Which of those two actually shrinks a turn, and which does not.** Measured\n2026-08-09, and worth stating plainly because the distinction is not obvious:\n\n- The **PreToolUse rewriter** changes the command *before* it runs, so a\n  smaller output is produced and a smaller output reaches the model. This is\n  a real reduction in the current turn.\n- The **PostToolUse compactors** run *after* the tool has returned. A\n  PostToolUse hook can only *add* context; by the time it fires, the raw\n  output has already been sent. The compact rendering is appended, it does\n  not replace anything. What the compactors genuinely buy you is different\n  and still valuable: the full output is preserved in the capture sandbox and\n  survives a context compaction, so it can be queried later instead of being\n  re-run.\n\nIf your goal is a smaller turn, `TS_BASH_REWRITE=1` is the switch that does\nit. If your goal is to stop losing command output across compactions, that is\n`TS_BASH_COMPACT=1`.\n\n---\n\n## Profile comparison\n\n| Profile | Tools exposed | Manifest tokens | When to use |\n|---|---:|---:|---|\n| **`optimized`** | **15** | **~1.5 KT** | **Recommended default -- Pareto win on tsbench** |\n| `auto` | adaptive | ~1-2 KT | Per-client telemetry-based (experimental) |\n| `tiny` | 6 | ~0.6 KT | Minimal hot loop |\n| `lean` | 51 | ~4 KT | Legacy -- broader surface |\n| **`compact-only`** | **1** | **~0.3 KT** | **Bash layer only (rewriter + capture) -- you already run symbol nav elsewhere** |\n| `full` | 68 | ~6 KT | Everything exposed |\n\nYou probably want `optimized`.\n\n---\n\n## How it composes with adjacent tools\n\nToken Savior spans several layers, and most neighbouring tools occupy exactly\none of them. Overlap is opt-out per layer, so running both is usually fine once\nyou disable the half you already have. Thanks to @chirag127 for mapping this\nout in #45.\n\n| Tool | Layer | Overlap | What to do |\n|---|---|---|---|\n| RTK (repo currently unreachable) | PostToolUse Bash output compression | Same layer, same PostToolUse limit: neither shrinks the current turn | Pick one. `TS_BASH_COMPACT=0` to defer to RTK |\n| [serena](https://github.com/oraios/serena) | Symbol-graph navigation | Direct, with `find_symbol` / `get_dependents` | Run TS as `compact-only` if serena is your navigator |\n| codebase-memory | Persistent code graph | With the memory engine | `TS_MEMORY_DISABLE=1` |\n| Ponytail, Caveman | Output-side compression (code and prose) | Partial, output side only | Complementary, no knob needed |\n\nThe layers Token Savior owns that these do not: the PreToolUse Bash **rewriter**\n(it shrinks the command before it runs, not the output after), structural\n**editing** that keeps the index in sync, and the audit tools\n(`detect_breaking_changes`, `find_dead_code`, `analyze_config`).\n\nIf you only want the Bash layer, `TOKEN_SAVIOR_PROFILE=compact-only` advertises\na single tool and leaves the compactors and rewriter running. Of those two, the\nrewriter is the one that reduces the current turn.\n\n---\n\n## Token savings\n\n| Operation | Plain Claude | Token Savior | Reduction |\n|-----------|-------------:|-------------:|----------:|\n| `find_symbol(\"send_message\")` | 41M chars (full read) | 67 chars | **-99.9%** |\n| `get_function_source(\"compile\")` | grep + cat chain | 4.5K chars | direct |\n| `get_change_impact(\"LLMClient\")` | impossible | 16K chars | new capability |\n| 96-task tsbench (Opus, plain vs ts) | 17 221 active/task | **3 395 active/task** | **-80%** |\n| 7-day Bash output bench (v4.3) | ~30 K tokens/week | ~9.6 K tokens/week | **~20.4 K/week** |\n\n---\n\n## Install\n\n### pip (MCP server)\n\n```bash\npip install \"token-savior-recall[mcp]\"\n# Optional hybrid vector search:\npip install \"token-savior-recall[mcp,memory-vector]\"\n```\n\n### uvx (no venv, no clone)\n\n```bash\nuvx token-savior-recall\n```\n\n### Claude Code one-liner\n\n```bash\nclaude mcp add token-savior -- /path/to/venv/bin/token-savior\n```\n\n### Development\n\n```bash\ngit clone https://github.com/Mibayy/token-savior\ncd token-savior\npython3 -m venv .venv\n.venv/bin/pip install -e \".[mcp,dev]\"\npytest tests/ -q\n```\n\nSuite size: **1898 passed, 2 skipped** on main. CI green on Python\n3.11 / 3.12 / 3.13.\n\n---\n\n## Bench it yourself\n\nThe compactor numbers above come from replaying real Claude Code\ntranscripts through the dispatcher. Two scripts live under `scripts/`:\n\n```bash\npython3 scripts/bench_compactors_real.py       # match rate + mean savings\npython3 scripts/bench_compactors_unmatched.py  # top unmatched commands\n```\n\nThe first walks `~/.claude/projects/*/*.jsonl`, replays every Bash\noutput through the registry, and reports per-family savings + overall\nmatch rate. The second buckets the unmatched commands so the next\ncompactor target is obvious from the histogram.\n\n### Reproducing the tsbench score\n\n**Honest status, checked 2026-08-09:** the benchmark repository these\ninstructions pointed at returns 404, and so did the BENCHMARK-SUMMARY link\nabove. Rather than leave a recipe that cannot run, here is what the harness\ndoes, so the number can be judged on its method:\n\n- A generated toy repo (deterministic seed) with four planted traps: a symbol\n  defined twice, a three-level call chain, an `a -> b -> c -> a` import cycle,\n  and a dead function whose name contains a live one.\n- Eight read-only tasks, scored mechanically against an `expected` list and a\n  `forbidden` list. The forbidden list is the half that matters: an answer can\n  contain the right target *and* the wrong one, and a grader that only looks\n  for the right one would score it correct.\n- A `sans_ts` control arm running plain Read/Grep/Glob, without which the\n  bench compares Token Savior profiles to each other and can never conclude\n  \"useless\" — and therefore never \"useful\" either.\n\nOne trap worth knowing about if you rebuild it: the harness spawns\n`claude -p`, which inherits `~/.claude/settings.json`. If any Token Savior\nPreToolUse hook is enabled on the machine, it applies to the control arm too\nand rigs the comparison. Neutralise them in both arms\n(`TS_GUARD_OFF=1 TS_READ_GUARD=0 TS_BASH_REWRITE=0`).\n\n---\n\n## Bonus: `ts` CLI for non-MCP agents\n\nFor agents without MCP (Cursor, Aider, Continue, scripts, CI), the `ts`\ncommand exposes a subset of the tools via shell:\n\n```bash\nts use /path/to/project\nts get my_function          # JSON output\nts search 'pattern'\nts daemon start             # ~145ms per call vs 1.5s cold fork\nts init --agent cursor      # wire up Bash hooks for non-Claude agents\n```\n\nOn Claude Code, prefer the MCP server -- measured cheaper than CLI on\nOpus 4.7. The CLI is there for the portability case.\n\n---\n\n## Environment variables\n\nAll optional. Values shown as `=1` also accept nothing else — set exactly `1`;\nvalues shown as *bool* accept `1`/`true`/`yes` (and `on` where noted).\n\n### Server & tool manifest\n\n| Var | Default | Purpose |\n|---|---|---|\n| `WORKSPACE_ROOTS` | current dir | Comma-separated project roots to index. Codex trap: Codex whitelist-filters the MCP server environment, so an exported shell variable never arrives — set it in `config.toml` under `[mcp_servers.token-savior] env` (or `env_vars`) |\n| `PROJECT_ROOT` | — | Single-root alternative to `WORKSPACE_ROOTS` |\n| `CLAUDE_PROJECT_ROOT` | — | Deliberate active-project override (Token Savior's own contract — no host sets it). Registered if valid, wins over every other boot signal |\n| `TS_STICKY_ACTIVE` | off (*bool*, `on` ok) | Freeze the active project: explicit `project=` hints and absolute path arguments still route each call, but no call repoints the shared default. For parallel agents in sibling worktrees |\n| `TOKEN_SAVIOR_PROFILE` | `full` | Tool profile. `optimized` — the value the quickstart config and `ts init` recommend — ships the Pareto manifest, implies thin schemas, and omits the capture tools from the manifest |\n| `TS_THIN_SCHEMAS=1` | off (on in `optimized`) | Strip verbose tool schemas from the manifest |\n| `TS_AUTO_HOT_K` | `10` | Hot-tool count exposed by the telemetry-driven `auto` profile |\n| `TOKEN_SAVIOR_CHAIN_NUDGE` | on | `0`/`false`/`off` disables chained-tool nudges |\n| `TS_MEMORY_DISABLE=1` | off | Disable the memory engine (clean-context workloads) |\n| `TS_CAPTURE_DISABLED=1` | off | Skip read-side capture sandboxing and drop the capture tools from the manifest (no profile flips this; `optimized` only hides the capture tools) |\n| `TS_CODE_MODE_DISABLE=1` | off | Disable code-mode tools |\n| `TS_CODE_MODE_NODE` | `node` | Node binary used by the code-mode sandbox |\n| `TS_RESOURCES_DISABLED` | off (*bool*) | Don't expose observations as `ts://obs/{id}` MCP resources |\n| `TS_WARM_START` | off (*bool*) | Pre-build project slots at startup |\n| `TOKEN_SAVIOR_NO_WARMUP` | off (*bool*) | Skip the `ts_search` embedding warm-up |\n| `TS_SEARCH_COLD_DELEGATE` | off (*bool*, `on` ok) | Delegate the cold `ts_search` call to a running `ts` daemon |\n| `TS_SOCK` | `/tmp/ts.sock` | Unix socket of the `ts` daemon (CLI + cold delegate) |\n| `TOKEN_SAVIOR_CLIENT` | auto-detected | Client label (`claude-code`, …) for telemetry/client detection |\n| `TOKEN_SAVIOR_SESSION_LABEL` | — | Free-form label attached to session telemetry |\n\n### Indexing\n\n| Var | Default | Purpose |\n|---|---|---|\n| `INCLUDE_PATTERNS` | built-in list | Colon-separated globs; **replaces** the default include list |\n| `EXCLUDE_PATTERNS` | built-in list | Colon-separated globs; **replaces** the default exclude list |\n| `EXCLUDE_EXTRA` | — | Colon-separated globs **appended** to the default excludes |\n| `TOKEN_SAVIOR_EXCLUDE_PATTERNS` | — | Colon-separated globs appended at the indexer level |\n| `TOKEN_SAVIOR_MAX_FILE_SIZE` | `500000` | Max file size (bytes) to index |\n| `TOKEN_SAVIOR_MAX_FILES` | `10000` | Max files per project |\n| `TOKEN_SAVIOR_WATCHER` | `auto` | File watcher: `auto` / `on` / `off` |\n| `TS_WATCHER_FORCE_POLLING` | off | Force the polling watcher backend |\n\n### Claude Code hooks\n\n| Var | Default | Purpose |\n|---|---|---|\n| `TS_CAPTURE_THRESHOLD_BYTES` | `4096` | Minimum tool-output size to sandbox |\n| `TS_CAPTURE_REPLACE=1` | off | Strong-replace: tell the agent to ignore the inline output and `capture_get` the URI |\n| `TS_CAPTURE_TTL_DAYS` | `30` | Captures older than this are purged on the next `capture_put`; `0` disables the GC |\n| `TS_BASH_COMPACT=1` | off | PostToolUse compactors. Preserves output across compaction; does NOT shrink the current turn (see note above) |\n| `TS_COMPACT_INLINE_THRESHOLD` | `4096` | Hybrid mode: compact-result size above which the full original is also sandboxed |\n| `TS_COMPACT_TINY_THRESHOLD` | `256` | Hybrid mode: compact-result size below which the sandbox is always skipped |\n| `TS_BASH_REWRITE=1` | off | Enable the PreToolUse Bash command rewriter |\n| `TS_BASH_REWRITE_LOG` | — | JSONL audit log of every rewrite |\n| `TS_HOOK_MINIMAL=1` | off | SessionStart memory hook emits only the Memory Index block |\n\n### Memory extras\n\n| Var | Default | Purpose |\n|---|---|---|\n| `TS_VIEWER_PORT` | off | Port for the observation web viewer (unset = disabled) |\n| `TS_AUTO_EXTRACT=1` + `TS_API_KEY` | off | LLM auto-extraction of memory observations (Anthropic API key required) |\n| `TS_MODEL` | `claude-sonnet-4-6` | Auto-extraction model override |\n| `TOKEN_SAVIOR_MEMORY_AUTO_SAVE=1` | off | Auto-save memory observations |\n| `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` | — | Critical-observation feed |\n\n### Storage, dashboard, debugging\n\n| Var | Default | Purpose |\n|---|---|---|\n| `TOKEN_SAVIOR_STATS_DIR` | `~/.local/share/token-savior` | Telemetry + stats directory |\n| `TOKEN_SAVIOR_DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind host |\n| `TOKEN_SAVIOR_DASHBOARD_PORT` | `8921` | Dashboard port |\n| `TOKEN_SAVIOR_INCLUDE_TMP_PROJECTS` | off (*bool*) | Dashboard also lists projects under temp dirs |\n| `TOKEN_SAVIOR_DEBUG=1` | off | Debug logging |\n| `TOKEN_SAVIOR_TRACE` | off (*bool*) | MCP request lifecycle tracing |\n\nNot knobs: `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CLAUDE_PROJECT_DIR`,\n`CLAUDE_CONTEXT_REMAINING_PCT`, `CODEX_*` and `HERMES_*` are read for host/client\ndetection and boot-time project hints — the environment sets them, you don't.\n(`CLAUDE_PROJECT_DIR` is what Claude Code actually exports; it always names the\nmain checkout, never the worktree the session works in, so the launch directory\noutranks it when that directory is a linked worktree. `CLAUDE_PROJECT_ROOT`\nmoved up into the knobs table: nothing sets it but you.)\n\nNaming trap: `TS_PROFILE` in the benchmark snippets is **tsbench's** variable;\nthe server reads `TOKEN_SAVIOR_PROFILE`.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 21384,
  "sha": "3131900740e872170910ed2c76db6849beb745f021f715fa76dc2df74ced7f1d",
  "repo_slug": "mibayy/token-savior",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mibayy_token_savior_9a9fe8f8/readme"
}