LeanToken

Measured token savings: In a controlled 60-run study, LeanToken used20.1% fewer model input tokens than the agent's built-in tools with limitedrepository exploration, and 37.6% fewer than those tools with broadexploration. See exactlyhow it was measured in the measurement methodology.

Quick start

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

npx leantoken setup

Current releases stop setup before writing when npx resolves a staleproject-local or ancestor install, and point tonpx leantoken@latest setup. Older releases that predate this check can bebootstrapped directly with that versioned command.

The interactive setup wizard preselects supported clients it detects; you canchange that selection before continuing. It then shows the exact configurationpaths and MCP launcher and asks for a separate final confirmation. Automationnever treats detection as consent. An npx-based setup pins the exact LeanTokenversion that ran setup, so restarting a client cannot silently move to a newerrelease.

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

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

npx leantoken doctor

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

Inspect LeanToken's observed repository-local token accounting:

npx leantoken savings

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

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

For regular use, --private-runtime is the recommended launcher: it copies theexact package-native executable into LeanToken's versioned application-datadirectory so clients launch one verified process directly, without persistentnpm/Node wrappers. It remains opt-in so the zero-install path does not add anapplication-data write. Preview its path and digest with --dry-run.

Automation never treats detection as consent: --yes requires explicit clientflags, --all, or --refresh for entries already managed by LeanToken. Previewthe 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 inthe directories used by the selected hosts: Claude Code uses ~/.claude, whileCodex and the other supported hosts use ~/.agents. The skill advertisesrouting metadata; it does not duplicate tool schemas, add rules, or installshell hooks. Setup marks new MCP launchers as managed and refuses to replace asame-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 versions and preview areference-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 newversion, or use an older version to roll back:

npx --yes leantoken@latest setup --refresh --yes
npx --yes [email protected] setup --refresh --yes --allow-outdated

Common agent workflows

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

1. Orient autonomous triage in one call. Start an uncertain broad task withcontext and plan_only: false, then use the materialized evidencedirectly. Make at most one focused follow-up only when coverage identifies aconcrete missing implementation or regression-test owner.
2. Continue without resending source. Pass the prior receipt_id on thenext context call, or pass returned fragment hashes as known_hashes. Theresponse reports exact and overlapping omissions instead of silentlycharging the same evidence again.
3. Investigate an observed failure. Use the investigation workflow andprovide only directly observed failure_traces, paths, symbols, or testintent in workflow_evidence. Follow with exact search, outline, orread calls for the owners the evidence identifies.
4. Review a change. Use the review workflow with base_revision set toBASE..HEAD and strict_changed_paths: true. Request a handoff whenanother 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 onimplementation agents. Human review and control-plane flows can still previewexpensive or high-risk retrieval with plan_only: true before materializing.The repeated multi-agent context suitefound that an iterative LeanToken profile used 50.9% more total input than thinnative, while the frozen one-context-plus-optional-one-search profile saved20.1% and had 15/20 path-set successes. Those results cover four pinned triagetasks; they do not prove a universal implementation workflow.

Explicit focus constraints are contracts. When a request suppliesfocus_paths, exact focus_symbols, andminimum_fragments_per_focus_path, LeanToken generates candidates within thedocumented per-file bounds and reports a coverage failure when distinct rangescannot satisfy the minimum. Explain-profile plans and materialized responsesalso 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 narrowsthat 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 andreads as the agent needs them.

Example

For a task like fix request cancellation during shutdown, an illustrativebounded 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 toosmall, the response also says what was left out. Paths, scores, receipts, JSON,and MCP transport wrappers are not part of this source-token budget; seetoken accounting for the measured boundaries.

Available tools

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

For autonomous broad triage, set plan_only: false and use the materializedevidence directly. Reserve plan_only: true for human or control-plane reviewbefore expensive or high-risk retrieval: it returns bounded ranked candidatemetadata without source fragments or receipt mutation. After approval, repeatthe same request with plan_only: false. Set response_profile: "compact" forthe smallest fail-loud response, keep the default "balanced" shape, or use"explain" for bounded individual omissions, facets, and diff evidence. Theresponse reports the resolved choice as effective_response_profile.

The catalog stays intentionally small because every tool description andschema 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 arepository 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 stablenormalized JSON schema. The auditor is local, bounded, and read-only withrespect to its input. It retains artifact hashes, not raw prompts, source, toolarguments, or tool outputs.

npm install leantoken installs the command in the current project'snode_modules/.bin; it does not add leantoken to the shell PATH. Invoke aproject-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 MCPclient 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. Registryclients that support Cargo packages can install the matching leantokenversion 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 apostinstall 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 --git https://github.com/morluto/leantoken --package leantoken leantoken

Updating

MCP entries created through npx stay pinned to the exact LeanToken versionthat 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 notavailable locally or online, startup fails rather than selecting another version.Updating the CLI does not change existing MCP entries. See theusage 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 prune --older-than 30 --dry-run
leantoken cache prune --max-total-bytes 1073741824 --yes

See the usage guide for cache states, pagination, and cleanupsafety 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 avoidsresending unchanged evidence across turns.

Dependency-heavy workspaces can opt into a separate, cache-identifiedfirst-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 orscoped, so an empty scoped result is never presented as whole-repositoryabsence. 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