# π§ pi-tokensaver
**Give your AI coding agent a semantic memory for your codebase**
[](https://www.npmjs.com/package/pi-tokensaver)
[](https://github.com/xilnick/pi-tokensaver/blob/main/LICENSE)
[](https://github.com/mariozechner/pi-coding-agent)
*A [Pi coding agent](https://github.com/mariozechner/pi-coding-agent) extension that bridges [tokensave](https://github.com/nicr9/tokensave) β a Rust-powered local semantic graph engine β directly into your AI pair-programming workflow.*
[Why?](#-why) β’ [How it works](#-how-it-works) β’ [Install](#-install) β’ [Usage](#-usage) β’ [Architecture](#-architecture) β’ [Configuration](#-configuration)
---
## π€ Why?
When you ask an AI agent to explore a codebase, it typically:
- π Runs `grep`, `glob`, `find` β scanning thousands of lines
- π Reads entire files just to find one function
- πΈ **Burns through your token budget** on redundant file reads
**tokensave** fixes this by building a **local semantic graph** of your code β functions, types, call relationships, imports β and exposing it as an MCP server with query tools. `pi-tokensaver` bridges that server into the Pi agent, so your AI gets **precision code exploration** instead of brute-force file scanning.
**Result:** Dramatically fewer tokens consumed per codebase query. Your agent finds what it needs in one semantic lookup instead of reading 20 files.
---
## β‘ How it works
```
ββββββββββββββββββββββββ ββββββββββββββββββββββββ
β β β β
β Pi Coding Agent β calls β pi-tokensaver β
β (LLM) ββββββββββΊβ (this extension) β
β β β β
ββββββββββββββββββββββββ ββββββββββββ¬ββββββββββββ
β JSON-RPC over stdio
βΌ
ββββββββββββββββββββββββ
β β
β tokensave serve β
β (MCP server) β
β queries semantic β
β graph locally β
β β
ββββββββββββββββββββββββ
β reads
βΌ
ββββββββββββββββββββββββ
β .tokensave/ β
β (local graph DB) β
ββββββββββββββββββββββββ
```
The extension manages the **full lifecycle** automatically:
| Phase | What happens |
|-------|-------------|
| **1. Init** | Runs `tokensave sync` to build/update the semantic graph. Ensures `.tokensave/` is gitignored. |
| **2. Registration** | Spawns `tokensave serve`, performs MCP handshake, discovers all available tools, and bridges each one as a Pi tool prefixed with `tokensave_`. |
| **3. Prompt Injection** | Injects a system prompt rule telling the LLM to prefer tokensave tools over raw grep/glob/read. |
| **4. Teardown** | Gracefully kills the `tokensave serve` process when the Pi session ends. |
---
## π¦ Install
### Prerequisites
1. **[Pi coding agent](https://github.com/mariozechner/pi-coding-agent)** β the AI agent framework.
2. **[tokensave](https://github.com/nicr9/tokensave)** β the Rust semantic graph engine:
```bash
cargo install tokensave
```
### Install the extension
One command β installs globally, works across all your projects automatically:
```bash
pi install npm:pi-tokensaver
```
That's it. Pi auto-discovers the extension from the global install. No per-project config needed.
> **Uninstall:** `pi remove npm:pi-tokensaver`
---
## π Usage
Once installed, it Just Worksβ’ β no manual setup required.
1. **Start a Pi session** in any project directory:
```bash
pi
```
2. The extension automatically:
- Detects and syncs the semantic graph for your project
- Spawns the MCP server in the background
- Registers semantic exploration tools (e.g. `tokensave_search`, `tokensave_related`)
- Tells the LLM to prefer these tools over brute-force file reads
3. **Ask your agent anything** β it will use the semantic graph for efficient exploration:
> *"Where is the authentication middleware applied?"*
> *"Which functions call `processPayment`?"*
> *"Show me the type hierarchy for `UserEvent`"*
### What if tokensave isn't installed?
The extension fails gracefully β you'll see a notification with install instructions, and the Pi session continues normally without tokensave tools.
---
## ποΈ Architecture
### MCP Client
The extension implements a lightweight **JSON-RPC 2.0 client over stdio** that speaks the [Model Context Protocol](https://modelcontextprotocol.io/). It handles:
- Process lifecycle (spawn, heartbeat, graceful shutdown with SIGTERMβSIGKILL fallback)
- Message framing (newline-delimited JSON)
- Request/response correlation with pending promise tracking
- Clean error propagation from MCP server errors
### Tool Bridge
Each MCP tool discovered from `tokensave serve` is converted into a Pi custom tool:
- **Schema conversion:** MCP JSON Schema β TypeBox schema for Pi parameter validation
- **Call forwarding:** Pi tool calls are proxied to the MCP server via JSON-RPC
- **Result mapping:** MCP response content is flattened into Pi's text-based result format
### Type Safety
Written in strict TypeScript with full type coverage for:
- JSON-RPC message types
- MCP tool definitions and responses
- Pi `ExtensionAPI` surface
- TypeBox schema construction
---
## βοΈ Configuration
No configuration needed β the extension auto-detects everything from your project root.
### Build from source
```bash
git clone https://github.com/xilnick/pi-tokensaver.git
cd pi-tokensaver
npm install
npm run build
```
---
## π License
[MIT](LICENSE) Β© contributors
---
**Made with π§ for [Pi](https://github.com/mariozechner/pi-coding-agent) + [tokensave](https://github.com/nicr9/tokensave)**
[Report a Bug](https://github.com/xilnick/pi-tokensaver/issues) Β· [Request a Feature](https://github.com/xilnick/pi-tokensaver/issues) Β· [Contribute](https://github.com/xilnick/pi-tokensaver/pulls)