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

Setup behavior and safety

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 interactive setup wizard preselects supported clients it detects; you can change that selection before continuing. It then shows the exact configuration paths and MCP launcher and asks for a separate final confirmation. Automation never treats detection as consent. 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.

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

Local by default

Source is indexed on your machine in a local database. LeanToken is a read-only discovery and retrieval layer.

Explicit token budgets

Every response has an explicit token limit, so large files cannot take over the request.

Built for agent workflows

Find files, search code, inspect structure, read exact ranges, trace history, query JSON, and track token usage through focused tools.

Advanced setup and version management

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

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

npx leantoken setup --all --yes

For regular use, --private-runtime is the recommended launcher: it copies the exact package-native executable into an application-data directory named by version and full BLAKE3 digest, so clients launch one verified process directly, without persistent npm/Node wrappers. Different source builds of one version can coexist. setup --refresh --private-runtime pins the current exact artifact; other referenced artifacts stay usable. It remains opt-in so the zero-install path does not add an application-data write. 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:

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

Setup adds the leantoken MCP entry plus a small owned discovery skill only in the directories used by the selected hosts: Claude Code uses ~/.claude, while Codex and the other supported hosts use ~/.agents. The skill advertises routing metadata; it does not duplicate tool schemas, add rules, or install shell hooks. Setup marks new MCP launchers as managed and refuses to replace a same-name manual entry unless you review the dry-run and pass --force-unmanaged. Remove the owned integration with:

npx leantoken remove

After private-runtime upgrades, inspect retained artifacts and preview a reference-safe cleanup before applying it:

npx leantoken runtime list

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

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

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

Advanced retrieval controls

Every index-backed retrieval tool, including receipt_rebase, accepts consistency: "reconcile_working_tree" when completed edits must be reconciled before the query. The default, "indexed_generation", returns the latest completed index generation without scanning or waiting for filesystem changes; it is not a Git revision boundary. leantoken.history reads immutable Git objects and leantoken.json reads exact live files, so neither accepts an index consistency mode. To constrain context to immutable history, pass BASE..HEAD as leantoken.context.base_revision with strict_changed_paths: true.

For autonomous broad triage, set plan_only: false and use the materialized evidence directly. Reserve plan_only: true for human or control-plane review before expensive or high-risk retrieval: it returns bounded ranked candidate metadata without source fragments or receipt mutation. After approval, repeat the same request with plan_only: false. Set response_profile: "compact" for the smallest