⚔ token-savior

Stop feeding your AI entire codebases. Give it a scalpel instead.

---

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

Project	Sessions	Queries	Chars used	Chars (naive)	Saving
project-alpha	35	360	4,801,108	639,560,872	99%
project-beta	26	189	766,508	20,936,204	96%
project-gamma	30	232	410,816	3,679,868	89%
TOTAL	92	782	5,981,476	664,229,092	99%

"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)

Query	RMLPlus	FastAPI	Django	CPython
find_symbol	0.01ms	0.01ms	0.03ms	0.08ms
get_dependencies	0.00ms	0.00ms	0.00ms	0.01ms
get_change_impact	0.02ms	0.00ms	2.81ms	0.45ms
get_function_source	0.01ms	0.02ms	0.03ms	0.10ms

Index build performance

Project	Files	Lines	Index time	Memory
Small project	36	7,762	0.9s	2.4 MB
FastAPI	2,556	332,160	5.7s	55 MB
Django	3,714	707,493	36.2s	126 MB
CPython	2,464	1,115,334	55.9s	197 MB

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

---

What it covers

Language / Type	Files	Extracts
Python	.py, .pyw	Functions, classes, methods, imports, dependency graph
TypeScript / JS	.ts, .tsx, .js, .jsx	Functions, arrow functions, classes, interfaces, type aliases
Go	.go	Functions, methods (receiver), structs, interfaces, type aliases
Rust	.rs	Functions, structs, enums, traits, impl blocks, macro_rules
C#	.cs	Classes, interfaces, structs, enums, methods, XML doc comments
Markdown / Text	.md, .txt, .rst	Sections via heading detection
JSON	.json	Nested key structure up to depth 4, $ref cross-references
Everything else	*	Line counts (generic fallback)

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

Tool	What it does
find_symbol	Where a symbol is defined — file, line, type, 20-line preview
get_function_source	Full source of a function or method
get_class_source	Full source of a class
get_functions	All functions in a file or project
get_classes	All classes with methods and bases
get_imports	All imports with module, names, line
get_structure_summary	File or project structure at a glance
list_files	Indexed files with optional glob filter
get_project_summary	File count, packages, top classes/functions
search_codebase	Regex search across all indexed files
reindex	Force full re-index (rarely needed)

Impact analysis

Tool	What it does
get_dependencies	What a symbol calls/uses
get_dependents	What calls/uses a symbol
get_change_impact	Direct + transitive dependents in one call
get_call_chain	Shortest dependency path between two symbols (BFS)
get_file_dependencies	Files imported by a given file
get_file_dependents	Files that import from a given file

Git & diffs

Tool	What it does
get_git_status	Branch, ahead/behind, staged, unstaged, untracked
get_changed_symbols	Changed files as symbol-level summaries, not diffs
get_changed_symbols_since_ref	Symbol-level changes since any git ref
summarize_patch_by_symbol	Compact review view — symbols instead of textual diffs
build_commit_summary	Compact commit summary from changed files

Safe editing

Tool	What it does
replace_symbol_source	Replace a symbol's source without touching the rest of the file
insert_near_symbol	Insert content before or after a symbol
create_checkpoint	Snapshot a set of files before editing
restore_checkpoint	Restore from checkpoint
compare_checkpoint_by_symbol	Diff checkpoint vs current at symbol level
list_checkpoints	List available checkpoints

Test & run

Tool	What it does
find_impacted_test_files	Infer likely impacted pytest files from changed symbols
run_impacted_tests	Run only impacted tests — compact summary, not raw logs
apply_symbol_change_and_validate	Edit + run impacted tests in one call
apply_symbol_change_validate_with_rollback	Edit + validate + auto-rollback on failure
discover_project_actions	Detect test/lint/build/run commands from project files
run_project_action	Execute a discovered action with bounded output

Stats

Tool	What it does
get_usage_stats	Cumulative token savings per project across sessions

---

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.

---

Works with any MCP-compatible AI coding tool.
Claude Code · Cursor · Windsurf · Cline · Continue · Hermes · any custom MCP client