token-savior

Builds a persistent ProjectIndex by dispatching files to language-specific annotators (high-fidelity for Python, TypeScript, Go, Rust, C#; fallback for Markdown, JSON, text). Uses AST-based parsing to extract entities (functions, classes, imports) and their relationships rather than treating code as raw text. The index persists across sessions, enabling zero-cost reuse of structural knowledge.

Exposes 34+ specialized query tools that retrieve only the relevant source lines for a specific symbol (function, class, method) without including the entire file. Uses the structural index to map symbol names to exact line ranges, then returns only those lines. Supports nested symbol queries (e.g., method within class) and handles language-specific scoping rules.

Creates checkpoints before editing operations and enables rollback to previous states if validation fails. Stores checkpoint metadata (timestamp, symbol, change description) and allows reverting to any checkpoint within a session. Uses file-based or version-control-aware storage to persist checkpoints.

Provides high-level workflow tools (workflow_ops) that combine multiple low-level operations (edit, re-index, test, validate) into single atomic workflows. Workflows are defined as sequences of operations with error handling and rollback logic. Enables AI agents to perform complex refactoring tasks without manual orchestration.

Exposes 106+ specialized tools via the Model Context Protocol (MCP) standard, covering code navigation, editing, analysis, and workflow operations. Tools are registered in a schema-based function registry that supports MCP-compatible clients (Claude Code, Cursor, Windsurf). Implements all tools with zero external dependencies beyond Python standard library.

Monitors the file system for changes and incrementally re-indexes affected files rather than rebuilding the entire ProjectIndex. Uses file-watch events (or polling) to detect modifications and updates only the changed symbols in the index. Maintains index consistency across concurrent edits.

Builds and traverses a dependency graph that maps call chains and transitive relationships between symbols. When a symbol is modified, the system can identify all downstream dependents (what might break) and upstream dependencies (what this symbol depends on). Uses graph traversal algorithms to compute impact scope without re-scanning the codebase.

Provides safe editing operations (edit_ops, compact_ops) that replace symbol source code without manual line-range calculations. After editing, automatically re-indexes the affected file and validates the change by running impacted tests. Uses checkpoints and rollback capabilities to ensure codebase integrity if validation fails.

Integrates with git to summarize changes at the symbol level rather than raw line diffs. When a file is modified, the system maps changed lines back to symbols and reports what symbols were added, removed, or modified. Provides a high-level view of code changes that is more meaningful to AI agents than raw diffs.

Uses the dependency graph to automatically identify which tests are affected by a code change, then executes only those tests. Avoids running the full test suite by computing the transitive closure of changed symbols and finding tests that depend on them. Integrates with common test frameworks (pytest, Jest, etc.).

Maintains a persistent memory engine that stores context and query results across MCP sessions. When an AI agent reconnects, it can access previously indexed data, query results, and session state without re-indexing or re-querying. Uses local storage (file-based or database) to persist the ProjectIndex and query cache.

Dispatches files to language-specific annotators that extract entities (functions, classes, methods, imports, exports) with language-specific semantics. High-fidelity annotators for Python, TypeScript, Go, Rust, and C# use AST parsing to understand scoping rules, decorators, type annotations, and module systems. Fallback annotators for Markdown, JSON, and text use pattern matching.

Supports indexing multiple workspace roots simultaneously, enabling navigation across monorepos and multi-project setups. Maintains separate ProjectIndex instances for each root but allows cross-root queries and dependency tracking. Handles workspace configuration via environment variables or config files.

Tracks every character returned to the AI via token-savior tools versus what would have been returned by naive approaches (e.g., cat, full-file reads). Persists metrics to a local database and exposes them via a web dashboard. Calculates token savings percentage and provides usage statistics per tool, per session, and per codebase.