leantoken

LeanToken

Code intelligence for agents: find the code that matters and keep your context window and tokens lean.

Language: English · 简体中文 · 日本語 · 한국어

• MCP Registry name: mcp-name: io.github.morluto/leantoken

Install · Why LeanToken · Tools · CLI · How it works · Docs

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.

Quick start

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

npx leantoken setup

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

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:

npx leantoken savings

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

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

npx leantoken remove

npx leantoken runtime list
npx leantoken runtime prune --dry-run
npx leantoken runtime prune --yes

npx --yes leantoken@latest setup --refresh --yes
npx --yes leantoken@0.1.8 setup --refresh --yes --allow-outdated

Common agent workflows

LeanToken works best as a small evidence loop rather than a one-shot repository
dump:

1. Orient autonomous triage in one call. Start an uncertain broad task with
   context and plan_only: false, then use the materialized evidence
   directly. Make at most one focused follow-up only when coverage identifies a
   concrete missing implementation or regression-test owner.
2. Continue without resending source. Pass the prior receipt_id on the
   next context call, or pass returned fragment hashes as known_hashes. The
   response reports exact and overlapping omissions instead of silently
   charging the same evidence again.
3. Investigate an observed failure. Use the investigation workflow and
   provide only directly observed failure_traces, paths, symbols, or test
   intent in workflow_evidence. Follow with exact search, outline, or
   read calls for the owners the evidence identifies.
4. Review a change. Use the review workflow with base_revision set to
   BASE..HEAD and strict_changed_paths: true. Request a handoff when
   another agent needs a compact manifest of selected hashes, changed paths,
   assumptions, and completed validations without copied source bodies.

This one-call contract is for autonomous repository triage, not a limit on
implementation agents. Human review and control-plane flows can still preview
expensive or high-risk retrieval with plan_only: true before materializing.
The repeated multi-agent context suite
found that an iterative LeanToken profile used 50.9% more total input than thin
native, while the frozen one-context-plus-optional-one-search profile saved
20.1% and had 15/20 path-set successes. Those results cover four pinned triage
tasks; they do not prove a universal implementation workflow.

Explicit focus constraints are contracts. When a request supplies
focus_paths, exact focus_symbols, and
minimum_fragments_per_focus_path, LeanToken generates candidates within the
documented per-file bounds and reports a coverage failure when distinct ranges
cannot satisfy the minimum. Explain-profile plans and materialized responses
also identify the bounded allocation boundary that generated, reserved,
selected, or suppressed each focus candidate without changing ranking.

Why LeanToken

Most agents start by searching widely and reading whole files. LeanToken narrows
that work in stages:

Your coding agent still handles editing, commands, tests, and conversation.
LeanToken finds and returns the code those tasks need.

LeanToken does not create one giant prompt file. It answers focused searches and
reads as the agent needs them.

Example

For a task like fix request cancellation during shutdown, an illustrative
bounded result might look like this:

Budget: 1,200 source tokens

Selected evidence:
  src/services/executor.rs        lines 137-147, 251-259
  src/services/reconciliation.rs lines 148-175, 257-272

The agent receives these ranges instead of both full files. If the budget is too
small, the response also says what was left out. Paths, scores, receipts, JSON,
and MCP transport wrappers are not part of this source-token budget; see
token accounting for the measured boundaries.

Available tools

The catalog stays intentionally small because every tool description and
schema also consumes model context.

CLI usage

Run LeanToken directly through npx:

npx leantoken status
npx leantoken savings
npx leantoken doctor
npx leantoken --root /path/to/repo search handle_request

Or use a globally installed binary:

npm install --global leantoken@latest

leantoken --root /path/to/repo index
leantoken --root /path/to/repo search handle_request --mode identifier --max-tokens 800
leantoken --root /path/to/repo context \
  --task "fix request cancellation during shutdown" \
  --budget 2000

Audit an existing redacted experiment or host report without opening a
repository index:

leantoken episode audit \
  --adapter multi-agent-suite-v1 \
  --input benchmarks/reports/multi-agent-context-suite-v1-codex-0.144.1.json

The default projection is Markdown; add global --json for the stable
normalized JSON schema. The auditor is local, bounded, and read-only with
respect to its input. It retains artifact hashes, not raw prompts, source, tool
arguments, or tool outputs.

npm install leantoken installs the command in the current project's
node_modules/.bin; it does not add leantoken to the shell PATH. Invoke a
project-local install through npx leantoken, a package script, or
./node_modules/.bin/leantoken.

Run the MCP server manually over stdio:

leantoken --root /path/to/repo mcp

{
  "mcpServers": {
    "leantoken": {
      "command": "leantoken",
      "args": ["--root", "/path/to/repo", "mcp"]
    }
  }
}

For the Cargo distribution, install the published crate and point your MCP
client at the resulting executable:

cargo install leantoken --version VERSION
leantoken --root /path/to/repo mcp

The official MCP Registry entry is io.github.morluto/leantoken. Registry
clients that support Cargo packages can install the matching leantoken
version and use the mcp command shown above.

Installation options

The npm package includes native binaries for:

• macOS on ARM64 and x64
• glibc Linux on ARM64 and x64
• Windows on x64

Installation does not run lifecycle scripts or download an executable from a
postinstall hook. Other targets, including musl Linux, must build from source.
Install Rust 1.95 or later and a native C/C++ toolchain, then run:

cargo install --locked --git https://github.com/morluto/leantoken leantoken

Updating

MCP entries created through npx stay pinned to the exact LeanToken version
that configured them. Update existing client integrations explicitly:

npx --yes leantoken@latest setup --refresh --yes

For a globally installed CLI or a CLI installed with Cargo:

leantoken upgrade --check
leantoken upgrade --yes

update is an alias for upgrade. For a project-local npm installation:

npm install leantoken@latest

Pinned MCP entries never silently move to @latest. If the exact package is not
available locally or online, startup fails rather than selecting another version.
Updating the CLI does not change existing MCP entries. See the
usage guide for rollbacks, cache management, and version details.

Cache management

Inspect local repository caches or preview cleanup before applying it:

leantoken cache list
leantoken cache list --summary
leantoken cache list --incompatible-with-current
leantoken cache prune --incompatible-with-current
leantoken cache compact --id v15-0123456789abcdef --dry-run
leantoken cache prune --older-than 30 --dry-run
leantoken cache prune --max-total-bytes 1073741824 --yes

See the usage guide for cache states, pagination, and cleanup
safety rules.

How it works

repository
    │
    ▼
file discovery ──► code structure extraction ──► local search index
                                                    │
                                                    ▼
agent request ──► ranked / exact retrieval ──► focused code within a token budget

LeanToken indexes source once, then serves compact paths, ranked matches,
structural outlines, exact source ranges, and task-specific context. It avoids
resending unchanged evidence across turns.

Dependency-heavy workspaces can opt into a separate, cache-identified
first-party index without changing the default whole-repository behavior:

leantoken --index-include 'src/**' --index-include 'tests/**' index

Status and every retrieval disclose whether the active index is full or
scoped, so an empty scoped result is never presented as whole-repository
absence. See the usage guide for bounds,
cache identity, and MCP registration examples.

LeanToken's goal is to return the code an agent needs with fewer input tokens.

Documentation

License

Licensed under either of the following, at your option:

• Apache License, Version 2.0
• MIT License