aovestdipaperino/tokensave

Semantic Code Intelligence for AI Coding Agents

Fewer tokens • Fewer tool calls • 100% local

---

Why tokensave?

AI coding agents waste tokens exploring codebases. Every grep, glob, and file read costs money. On complex tasks, agents spawn multiple Explore sub-agents that scan hundreds of files just to build context.

tokensave gives agents a pre-indexed semantic knowledge graph. Instead of scanning files, the agent queries the graph and gets instant, structured answers – the right symbols, their relationships, and source code, in one call.

How It Works

flowchart TB
    subgraph agent["AI Coding Agent (Claude Code, Codex, Gemini, Cursor, ...)"]
        task["Implement user authentication"]
        first["Sub-agent"]
        second["Sub-agent"]
        task --> first
        task --> second
        first --- second
    end

    subgraph server["tokensave MCP Server"]
        search["Search: auth"]
        callers["Callers: login()"]
        context["Context for task"]
        db[("libSQL Graph DBInstant lookupsFTS5 search")]
        search --> db
        callers --> db
        context --> db
    end

    first --> search
    first --> callers
    second --> context

Without tokensave: Agents use grep, glob, and Read to scan files – many API calls, high token usage.

With tokensave: Agents query the graph via MCP tools – instant results, local processing, fewer tokens.

---

Key Features

---

Quick Start

1. Install

Choose one installation method:

You can also download a prebuilt binary and add it to your PATH.

To build unreleased code from the upstream master branch, see Installing from upstream master.

2. Configure your agent

Run the setup command to auto-detect your installed agents:

tokensave install

To choose an agent, use --agent (for example, codex, claude, or cursor):

tokensave install --agent codex

Setup registers the MCP server and the agent’s integration for Claude Code, Codex CLI, Gemini CLI, Cursor, Copilot, Kiro, Pi, Zed, and more than a dozen other agents. It also offers global Git hooks to keep initialized projects up to date. You can safely run setup again after upgrading. See Agent Integrations for project-local installs, several agents at once, and what setup writes for each agent.

3. Index your project

cd /path/to/your/project
tokensave init

This creates a .tokensave/ directory with the knowledge graph database. A repository you create with git init is initialized automatically on its first commit or agent session (auto_init, on by default). After that, tokensave sync updates the index incrementally, and a connected agent keeps it fresh automatically. Commands work from any subdirectory of the project. See Indexing and Freshness for details.

---

Documentation

The full documentation lives in docs/guide/ and is mirrored to the GitHub Wiki.

The long-form User Guide walks through everyday use in more depth. To contribute, see CONTRIBUTING.md.

---

Origin

This project is a Rust port of the original CodeGraph TypeScript implementation by @colbymchenry. The port maintains the same architecture and MCP tool interface while leveraging Rust for performance and native tree-sitter bindings.

---

Building

To build from source, see Building from source and CONTRIBUTING.md.

Star History

Sponsors

License

MIT License – see LICENSE for details.

tokensave.dev