leantoken

<div align="center">

<h1>LeanToken</h1>

**Make every AI coding token go further**

Local-first code intelligence for coding agents. Search code, inspect structure,
read exact ranges, and explore Git history through a CLI and MCP server.

**Language:** English · [简体中文](docs/i18n/zh-CN/README.md) · [日本語](docs/i18n/ja-JP/README.md) · [한국어](docs/i18n/ko-KR/README.md)

<img src="assets/leantoken-hero-v3.jpg" alt="LeanToken narrowing a large codebase to the files and code an AI agent needs" width="100%">

[![npm](https://img.shields.io/npm/v/leantoken?logo=npm&label=npm)](https://www.npmjs.com/package/leantoken)
[![npm downloads](https://img.shields.io/npm/dm/leantoken?logo=npm&label=downloads)](https://www.npmjs.com/package/leantoken)
[![Rust 1.95+](https://img.shields.io/badge/Rust-1.95%2B-000000?logo=rust)](https://www.rust-lang.org/)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)

[Install](#quick-start) · [Why LeanToken](#why-leantoken) · [Tools](#available-tools) · [CLI](#cli-usage) · [How it works](#how-it-works) · [Docs](#documentation)

</div>

---

> **Measured token savings:** In a controlled 60-run study, LeanToken used
> 20.1% fewer model input tokens than the agent's built-in tools with limited
> repository exploration, and 37.6% fewer than those tools with broad
> exploration. See exactly
> how it was measured in the [measurement methodology](docs/measurement.md).

## Quick start

Add LeanToken to Claude Code, Cursor, OpenCode, Codex, Gemini CLI, or
Antigravity:

```bash
npx leantoken setup
```

<details>
<summary><strong>Setup behavior and safety</strong></summary>

Current releases stop setup before writing when `npx` resolves a stale
project-local or ancestor install, and point to
`npx leantoken@latest setup`. Older releases that predate this check can be
bootstrapped directly with that versioned command.

The setup wizard labels supported clients it detects, but leaves every client
unselected so you choose exactly which coding agents receive LeanToken. Before
writing anything, it shows the exact configuration paths and MCP launcher and
asks for confirmation. An npx-based setup pins the exact LeanToken version
that ran setup, so restarting a client cannot silently move to a newer release.

Global setup never stores the repository where setup happened. OpenCode gets a
workspace-relative working directory; other supported clients launch LeanToken
from the workspace cwd selected by the host. If a host instead starts it from
the home directory or a filesystem root, LeanToken refuses to index that broad
root by default.

</details>

Restart or reload the configured clients, then verify the connection and first
retrieval from a repository:

```bash
npx leantoken doctor
```

Try a broad task such as: *Find the code related to request cancellation before
editing.* LeanToken helps the agent start with `leantoken.context`, while its
normal tools remain available for edits, builds, and tests.

Inspect LeanToken's observed repository-local token accounting:

```bash
npx leantoken savings
```

<table>
<tr>
<td width="33%" valign="top">
<strong>Local by default</strong><br><br>
Source is indexed on your machine in a local database. LeanToken is a read-only
discovery and retrieval layer.
</td>
<td width="33%" valign="top">
<strong>Explicit token budgets</strong><br><br>
Every response has an explicit token limit, so large files cannot take over the
request.
</td>
<td width="33%" valign="top">
<strong>Built for agent workflows</strong><br><br>
Find files, search code, inspect structure, read exact ranges, trace history,
query JSON, and track token usage through focused tools.
</td>
</tr>
</table>

<details>
<summary><strong>Advanced setup and version management</strong></summary>

To skip the wizard, select clients explicitly or configure all supported
clients:

```bash
npx leantoken setup --claude --codex --yes
npx leantoken setup --all --yes
```

Use `--private-runtime` to copy the exact package-native executable into
LeanToken's versioned application-data directory and configure clients to
launch it directly, without persistent npm/Node wrappers. Preview its path and
digest with `--dry-run`.

Automation never treats detection as consent: `--yes` requires explicit client
flags, `--all`, or `--refresh` for entries already managed by LeanToken. Preview
the same resolved plan without changing files:

```bash
npx leantoken setup --codex --cursor --dry-run
```

Setup adds the `leantoken` MCP entry plus a small owned discovery skill in the
host-standard user skill directories. The skill advertises routing metadata;
it does not duplicate tool schemas, add rules, or install shell hooks. Remove
the owned integration with:

```bash
npx leantoken remove
```

Refresh only existing LeanToken MCP entries after explicitly choosing a new
version, or use an older version to roll back:

```bash
npx --yes leantoken@latest setup --refresh --yes
npx --yes leantoken@0.

... (truncated)