An MCP server that indexes your codebase structurally and exposes surgical query tools — so your AI agent reads 200 characters instead of 200 files.

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)

Measured across 782 real sessions: 99% token reduction.

Why this exists

Every AI coding session starts the same way: the agent grabs cat or grep, reads a dozen files to find one function, then bloats its context trying to understand what else might break. By the end, half your token budget is gone before the first edit.

token-savior replaces that pattern entirely. It builds a structural index once, keeps it in sync with git automatically, and answers "where is X", "what calls X", and "what breaks if I change X" in sub-millisecond time — with responses sized to the answer, not the codebase.

Numbers

Token savings across real sessions

"Chars (naive)" = total source size of all files the agent would have read with cat/grep. These savings are model-agnostic — the index reduces context window pressure regardless of provider.

Query response time (sub-millisecond at 1.1M lines)

Index build performance

With the persistent cache, subsequent restarts skip the full build. CPython goes from 56s → under 1s on cache hit.

What it covers

A workspace pointing at /root indexes Python bots, docker-compose files, READMEs, skill files, and API configs in one pass. Any agent task benefits — not only code refactoring.

34 tools

Navigation

Impact analysis

Git & diffs

Safe editing

Test & run

Stats

vs LSP

LSP answers "where is this defined?" — token-savior answers "what breaks if I change it?"

LSP is point queries: one symbol, one file, one position. It can find where LLMClient is defined and who references it directly. Ask "what breaks transitively if I refactor LLMClient?" and LSP has nothing — the AI would need to chain dozens of find-reference calls recursively, reading files at every step.

get_change_impact("TestCase") on CPython finds 154 direct dependents and 492 transitive dependents in 0.45ms, returning 16K chars instead of reading 41M. And unlike LSP, it requires zero language servers — one binary covers Python + TS/JS + Go + Rust + C# + Markdown + JSON out of the box.

Install

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

Configure

Claude Code / Cursor / Windsurf / Cline

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT is optional but lets the live dashboard attribute savings by client.

Make the agent actually use it

AI assistants default to grep and cat even when better tools are available. Soft instructions get rationalized away. Add this to your CLAUDE.md or equivalent:

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

Multi-project workspaces

One server instance covers every project on the machine:

WORKSPACE_ROOTS=/root/myapp,/root/mybot,/root/docs token-savior

Each root gets its own isolated index, loaded lazily on first use. list_projects shows all registered roots. switch_project sets the active one.

How it stays in sync

The server checks git diff and git status before every query (~1-2ms). Changed files are re-parsed incrementally. No manual reindex after edits, branch switches, or pulls.

The index is saved to .codebase-index-cache.json after every build — human-readable JSON, inspectable when things go wrong, safe across Python versions.

Programmatic usage

from token_savior.project_indexer import ProjectIndexer
from token_savior.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project")
index = indexer.index()
query = create_project_query_functions(index)

print(query["get_project_summary"]())
print(query["find_symbol"]("MyClass"))
print(query["get_change_impact"]("send_message"))

Development

pip install -e ".[dev,mcp]"
pytest tests/ -v
ruff check src/ tests/

Known limitations

• Live-editing window: The index is git-aware and updates on query, not on save. If you edit a file and immediately call get_function_source, you may get the pre-edit version. The next git-tracked change triggers a re-index.
• Cross-language tracing: get_change_impact stops at language boundaries. Python calling a shell script calling a JSON config — the chain breaks after Python.
• JSON value semantics: The JSON annotator indexes key structure, not value meaning. Tracing what a config value propagates to across files is still manual.