Skip to content
Back to search

leantoken

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/morluto/leantoken with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/morluto/leantoken'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/morluto--leantoken/badge.svg)](/listings/morluto--leantoken)

HTML

<a href="/listings/morluto--leantoken"><img src="/api/listings/morluto--leantoken/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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 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.

</details>

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

<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:

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 LeanToken's versioned application-data directory so clients launch one verified process directly, without persistent npm/Node wrappers. 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 versions and preview a reference-safe cleanup before applying it:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 457 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <h1>LeanToken</h1>
  3. **Code intelligence for agents: find the code that matters and keep your context window and tokens lean.**
  4. **Language:** English · [简体中文](docs/i18n/zh-CN/README.md) · [日本語](docs/i18n/ja-JP/README.md) · [한국어](docs/i18n/ko-KR/README.md)
  5. - MCP Registry name: `mcp-name: io.github.morluto/leantoken`
  6. <img src="assets/leantoken-hero-v3.jpg" alt="LeanToken narrowing a large codebase to the files and code an AI agent needs" width="100%">
  7. [![npm](https://img.shields.io/npm/v/leantoken?logo=npm&label=npm)](https://www.npmjs.com/package/leantoken)
  8. [![npm downloads](https://img.shields.io/npm/dm/leantoken?logo=npm&label=downloads)](https://www.npmjs.com/package/leantoken)
  9. [![Rust 1.95+](https://img.shields.io/badge/Rust-1.95%2B-000000?logo=rust)](https://www.rust-lang.org/)
  10. [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)
  11. [Install](#quick-start) · [Why LeanToken](#why-leantoken) · [Tools](#available-tools) · [CLI](#cli-usage) · [How it works](#how-it-works) · [Docs](#documentation)
  12. </div>
  13. ---
  14. > **Measured token savings:** In a controlled 60-run study, LeanToken used
  15. > 20.1% fewer model input tokens than the agent's built-in tools with limited
  16. > repository exploration, and 37.6% fewer than those tools with broad
  17. > exploration. See exactly
  18. > how it was measured in the [measurement methodology](https://github.com/morluto/leantoken/blob/main/docs/measurement.md).
  19. ## Quick start
  20. Add LeanToken to Claude Code, Cursor, OpenCode, Codex, Gemini CLI, or
  21. Antigravity:
  22. ```bash
  23. npx leantoken setup
  24. ```
  25. <details>
  26. <summary><strong>Setup behavior and safety</strong></summary>
  27. Current releases stop setup before writing when `npx` resolves a stale
  28. project-local or ancestor install, and point to
  29. `npx leantoken@latest setup`. Older releases that predate this check can be
  30. bootstrapped directly with that versioned command.
  31. The interactive setup wizard preselects supported clients it detects; you can
  32. change that selection before continuing. It then shows the exact configuration
  33. paths and MCP launcher and asks for a separate final confirmation. Automation
  34. never treats detection as consent. An npx-based setup pins the exact LeanToken
  35. version that ran setup, so restarting a client cannot silently move to a newer
  36. release.
  37. Global setup never stores the repository where setup happened. OpenCode gets a
  38. workspace-relative working directory; other supported clients launch LeanToken
  39. from the workspace cwd selected by the host. If a host instead starts it from
  40. the home directory or a filesystem root, LeanToken refuses to index that broad
  41. root by default.
  42. </details>
  43. Restart or reload the configured clients, then verify the connection and first
  44. retrieval from a repository:
  45. ```bash
  46. npx leantoken doctor
  47. ```
  48. Try a broad task such as: *Find the code related to request cancellation before
  49. editing.* LeanToken helps the agent start with `leantoken.context`, while its
  50. normal tools remain available for edits, builds, and tests.
  51. Inspect LeanToken's observed repository-local token accounting:
  52. ```bash
  53. npx leantoken savings
  54. ```
  55. <table>
  56. <tr>
  57. <td width="33%" valign="top">
  58. <strong>Local by default</strong><br><br>
  59. Source is indexed on your machine in a local database. LeanToken is a read-only
  60. discovery and retrieval layer.
  61. </td>
  62. <td width="33%" valign="top">
  63. <strong>Explicit token budgets</strong><br><br>
  64. Every response has an explicit token limit, so large files cannot take over the
  65. request.
  66. </td>
  67. <td width="33%" valign="top">
  68. <strong>Built for agent workflows</strong><br><br>
  69. Find files, search code, inspect structure, read exact ranges, trace history,
  70. query JSON, and track token usage through focused tools.
  71. </td>
  72. </tr>
  73. </table>
  74. <details>
  75. <summary><strong>Advanced setup and version management</strong></summary>
  76. To skip the wizard, select clients explicitly or configure all supported
  77. clients:
  78. ```bash
  79. npx leantoken setup --claude --codex --yes
  80. npx leantoken setup --all --yes
  81. ```
  82. For regular use, `--private-runtime` is the recommended launcher: it copies the
  83. exact package-native executable into an application-data directory named by
  84. version and full BLAKE3 digest, so clients launch one verified process directly,
  85. without persistent npm/Node wrappers. Different source builds of one version
  86. can coexist. `setup --refresh --private-runtime` pins the current exact artifact;
  87. other referenced artifacts stay usable. It remains opt-in so the zero-install
  88. path does not add an application-data write. Preview its path and digest with
  89. `--dry-run`.
  90. Automation never treats detection as consent: `--yes` requires explicit client
  91. flags, `--all`, or `--refresh` for entries already managed by LeanToken. Preview
  92. the same resolved plan without changing files:
  93. ```bash
  94. npx leantoken setup --codex --cursor --dry-run
  95. ```
  96. Setup adds the `leantoken` MCP entry plus a small owned discovery skill only in
  97. the directories used by the selected hosts: Claude Code uses `~/.claude`, while
  98. Codex and the other supported hosts use `~/.agents`. The skill advertises
  99. routing metadata; it does not duplicate tool schemas, add rules, or install
  100. shell hooks. Setup marks new MCP launchers as managed and refuses to replace a
  101. same-name manual entry unless you review the dry-run and pass
  102. `--force-unmanaged`. Remove the owned integration with:
  103. ```bash
  104. npx leantoken remove
  105. ```
  106. After private-runtime upgrades, inspect retained artifacts and preview a
  107. reference-safe cleanup before applying it:
  108. ```bash
  109. npx leantoken runtime list
  110. npx leantoken runtime prune --dry-run
  111. npx leantoken runtime prune --yes
  112. ```
  113. Refresh only existing LeanToken MCP entries after explicitly choosing a new
  114. version, or use an older version to roll back:
  115. ```bash
  116. npx --yes leantoken@latest setup --refresh --yes
  117. npx --yes leantoken@0.1.8 setup --refresh --yes --allow-outdated
  118. ```
  119. </details>
  120. ## Common agent workflows
  121. LeanToken works best as a small evidence loop rather than a one-shot repository
  122. dump:
  123. 1. **Orient autonomous triage in one call.** Start an uncertain broad task with
  124. `context` and `plan_only: false`, then use the materialized evidence
  125. directly. Make at most one focused follow-up only when coverage identifies a
  126. concrete missing implementation or regression-test owner.
  127. 2. **Continue without resending source.** Pass the prior `receipt_id` on the
  128. next context call, or pass returned fragment hashes as `known_hashes`. The
  129. response reports exact and overlapping omissions instead of silently
  130. charging the same evidence again.
  131. 3. **Investigate an observed failure.** Use the `investigation` workflow and
  132. provide only directly observed `failure_traces`, paths, symbols, or test
  133. intent in `workflow_evidence`. Follow with exact `search`, `outline`, or
  134. `read` calls for the owners the evidence identifies.
  135. 4. **Review a change.** Use the `review` workflow with `base_revision` set to
  136. `BASE..HEAD` and `strict_changed_paths: true`. Request a `handoff` when
  137. another agent needs a compact manifest of selected hashes, changed paths,
  138. assumptions, and completed validations without copied source bodies.
  139. This one-call contract is for autonomous repository triage, not a limit on
  140. implementation agents. Human review and control-plane flows can still preview
  141. expensive or high-risk retrieval with `plan_only: true` before materializing.
  142. The [repeated multi-agent context suite](https://github.com/morluto/leantoken/blob/main/docs/measurement.md#repeated-multi-agent-context-suite)
  143. found that an iterative LeanToken profile used 50.9% more total input than thin
  144. native, while the frozen one-context-plus-optional-one-search profile saved
  145. 20.1% and had 15/20 path-set successes. Those results cover four pinned triage
  146. tasks; they do not prove a universal implementation workflow.
  147. Explicit focus constraints are contracts. When a request supplies
  148. `focus_paths`, exact `focus_symbols`, and
  149. `minimum_fragments_per_focus_path`, LeanToken generates candidates within the
  150. documented per-file bounds and reports a coverage failure when distinct ranges
  151. cannot satisfy the minimum. Explain-profile plans and materialized responses
  152. also identify the bounded allocation boundary that generated, reserved,
  153. selected, or suppressed each focus candidate without changing ranking.
  154. ## Why LeanToken
  155. Most agents start by searching widely and reading whole files. LeanToken narrows
  156. that work in stages:
  157. | Typical repository exploration | With LeanToken |
  158. | --- | --- |
  159. | Scan broad directory listings | Find relevant paths in a compact tree |
  160. | Read whole files to find structure | See definitions and imports without loading the entire file |
  161. | Send the same code again after each turn | Avoid repeating unchanged evidence |
  162. | Let large files fill the request | Keep returned source within an exact source-token budget and report response overhead separately |
  163. | Guess which files matter | Rank likely relevant code for the task |
  164. Your coding agent still handles editing, commands, tests, and conversation.
  165. LeanToken finds and returns the code those tasks need.
  166. LeanToken does not create one giant prompt file. It answers focused searches and
  167. reads as the agent needs them.
  168. ### Example
  169. For a task like *fix request cancellation during shutdown*, an illustrative
  170. bounded result might look like this:
  171. ```text
  172. Budget: 1,200 source tokens
  173. Selected evidence:
  174. src/services/executor.rs lines 137-147, 251-259
  175. src/services/reconciliation.rs lines 148-175, 257-272
  176. ```
  177. The agent receives these ranges instead of both full files. If the budget is too
  178. small, the response also says what was left out. Paths, scores, receipts, JSON,
  179. and MCP transport wrappers are not part of this source-token budget; see
  180. [token accounting](docs/usage.md#token-accounting) for the measured boundaries.
  181. ## Available tools
  182. | Tool | Purpose |
  183. | --- | --- |
  184. | `leantoken.context` | Default materialized first call for autonomous broad triage; optional preview for human or control-plane review. |
  185. | `leantoken.search` | Prefer over grep/rg for ranked search; exhaustive text/regex calls can explicitly record or reuse complete query coverage. |
  186. | `leantoken.files` | Prefer over find/ls/glob for compact, ignore-aware path discovery. |
  187. | `leantoken.outline` | Inspect definitions, signatures, imports, and ranges without whole-file reads. |
  188. | `leantoken.read` | Prefer over cat/head/sed for one exact symbol or inclusive line range. |
  189. | `leantoken.history` | Read, batch-diff, or trace parsed symbols across immutable Git revisions. |
  190. | `leantoken.json` | Query, summarize, or compare bounded live JSON with paged keys and typed diagnostics. |
  191. | `leantoken.receipt_rebase` | Explicitly carry only same-path, same-coordinate, same-hash evidence into a newer completed generation. |
  192. | `leantoken.savings` | Report observed response accounting, hash suppression, failures, and explicit observation limits. |
  193. <details>
  194. <summary><strong>Advanced retrieval controls</strong></summary>
  195. Every index-backed retrieval tool, including `receipt_rebase`, accepts
  196. `consistency: "reconcile_working_tree"` when completed edits must be reconciled
  197. before the query. The default,
  198. `"indexed_generation"`, returns the latest completed index generation without
  199. scanning or waiting for filesystem changes; it is not a Git revision boundary.
  200. `leantoken.history` reads immutable Git objects and `leantoken.json` reads exact
  201. live files, so neither accepts an index consistency mode. To constrain context
  202. to immutable history, pass `BASE..HEAD` as `leantoken.context.base_revision`
  203. with `strict_changed_paths: true`.
  204. For autonomous broad triage, set `plan_only: false` and use the materialized
  205. evidence directly. Reserve `plan_only: true` for human or control-plane review
  206. before expensive or high-risk retrieval: it returns bounded ranked candidate
  207. metadata without source fragments or receipt mutation. After approval, repeat
  208. the same request with `plan_only: false`. Set `response_profile: "compact"` for
  209. the smallest fail-loud response, keep the default `"balanced"` shape, or use
  210. `"explain"` for bounded individual omissions, facets, and diff evidence. The
  211. response reports the resolved choice as `effective_response_profile`.
  212. </details>
  213. The catalog stays intentionally small because every tool description and
  214. schema also consumes model context.
  215. ## CLI usage
  216. Run LeanToken directly through `npx`:
  217. ```bash
  218. npx leantoken status
  219. npx leantoken savings
  220. npx leantoken doctor
  221. npx leantoken --root /path/to/repo search handle_request
  222. ```
  223. Or use a globally installed binary:
  224. ```bash
  225. npm install --global leantoken@latest
  226. leantoken --root /path/to/repo index
  227. leantoken --root /path/to/repo search handle_request --mode identifier --max-tokens 800
  228. leantoken --root /path/to/repo context \
  229. --task "fix request cancellation during shutdown" \
  230. --budget 2000
  231. ```
  232. Audit an existing redacted experiment or host report without opening a
  233. repository index:
  234. ```bash
  235. leantoken episode audit \
  236. --adapter multi-agent-suite-v1 \
  237. --input benchmarks/reports/multi-agent-context-suite-v1-codex-0.144.1.json
  238. ```
  239. The default projection is Markdown; add global `--json` for the stable
  240. normalized JSON schema. The auditor is local, bounded, and read-only with
  241. respect to its input. It retains artifact hashes, not raw prompts, source, tool
  242. arguments, or tool outputs.
  243. `npm install leantoken` installs the command in the current project's
  244. `node_modules/.bin`; it does not add `leantoken` to the shell `PATH`. Invoke a
  245. project-local install through `npx leantoken`, a package script, or
  246. `./node_modules/.bin/leantoken`.
  247. Run the MCP server manually over stdio:
  248. ```bash
  249. leantoken --root /path/to/repo mcp
  250. ```
  251. <details>
  252. <summary><strong>Manual MCP client configuration</strong></summary>
  253. ```json
  254. {
  255. "mcpServers": {
  256. "leantoken": {
  257. "command": "leantoken",
  258. "args": ["--root", "/path/to/repo", "mcp"]
  259. }
  260. }
  261. }
  262. ```
  263. </details>
  264. For the Cargo distribution, install the published crate and point your MCP
  265. client at the resulting executable:
  266. ```bash
  267. cargo install leantoken --version VERSION
  268. leantoken --root /path/to/repo mcp
  269. ```
  270. The official MCP Registry entry is `io.github.morluto/leantoken`. Registry
  271. clients that support Cargo packages can install the matching `leantoken`
  272. version and use the `mcp` command shown above.
  273. ## Installation options
  274. The npm package includes native binaries for:
  275. - macOS on ARM64 and x64
  276. - glibc Linux on ARM64 and x64
  277. - Windows on x64
  278. Installation does not run lifecycle scripts or download an executable from a
  279. postinstall hook. Other targets, including musl Linux, must build from source.
  280. Install Rust 1.95 or later and a native C/C++ toolchain, then run:
  281. ```bash
  282. cargo install --locked --git https://github.com/morluto/leantoken leantoken
  283. ```
  284. ## Updating
  285. MCP entries created through `npx` stay pinned to the exact LeanToken version
  286. that configured them. Update existing client integrations explicitly:
  287. ```bash
  288. npx --yes leantoken@latest setup --refresh --yes
  289. ```
  290. For a globally installed CLI or a CLI installed with Cargo:
  291. ```bash
  292. leantoken upgrade --check
  293. leantoken upgrade --yes
  294. ```
  295. `update` is an alias for `upgrade`. For a project-local npm installation:
  296. ```bash
  297. npm install leantoken@latest
  298. ```
  299. Pinned MCP entries never silently move to `@latest`. If the exact package is not
  300. available locally or online, startup fails rather than selecting another version.
  301. Updating the CLI does not change existing MCP entries. See the
  302. [usage guide](docs/usage.md) for rollbacks, cache management, and version details.
  303. ## Cache management
  304. Inspect local repository caches or preview cleanup before applying it:
  305. ```bash
  306. leantoken cache list
  307. leantoken cache list --summary
  308. leantoken cache list --incompatible-with-current
  309. leantoken cache prune --incompatible-with-current
  310. leantoken cache compact --id v15-0123456789abcdef --dry-run
  311. leantoken cache prune --older-than 30 --dry-run
  312. leantoken cache prune --max-total-bytes 1073741824 --yes
  313. ```
  314. See the [usage guide](docs/usage.md) for cache states, pagination, and cleanup
  315. safety rules.
  316. ## How it works
  317. ```text
  318. repository
  319. │
  320. ▼
  321. file discovery ──► code structure extraction ──► local search index
  322. │
  323. ▼
  324. agent request ──► ranked / exact retrieval ──► focused code within a token budget
  325. ```
  326. LeanToken indexes source once, then serves compact paths, ranked matches,
  327. structural outlines, exact source ranges, and task-specific context. It avoids
  328. resending unchanged evidence across turns.
  329. Dependency-heavy workspaces can opt into a separate, cache-identified
  330. first-party index without changing the default whole-repository behavior:
  331. ```bash
  332. leantoken --index-include 'src/**' --index-include 'tests/**' index
  333. ```
  334. Status and every retrieval disclose whether the active index is full or
  335. scoped, so an empty scoped result is never presented as whole-repository
  336. absence. See the [usage guide](docs/usage.md#indexing-scope) for bounds,
  337. cache identity, and MCP registration examples.
  338. LeanToken's goal is to return the code an agent needs with fewer input tokens.
  339. ## Documentation
  340. | Guide | Contents |
  341. | --- | --- |
  342. | [Usage and tool reference](docs/usage.md) | Commands, MCP tools, request options, and examples |
  343. | [Architecture and reliability](docs/architecture.md) | Components, data flow, storage, and failure behavior |
  344. | [Roadmap](docs/roadmap.md) | Current direction and planned work |
  345. | [Development and testing](https://github.com/morluto/leantoken/blob/main/docs/development.md) | Local setup, validation, and release workflow |
  346. | [Benchmark methodology](https://github.com/morluto/leantoken/blob/main/benchmarks/README.md) | Token-economy measurements and interpretation |
  347. | [Measurement harnesses](https://github.com/morluto/leantoken/blob/main/docs/measurement.md) | Experiment, wire-cost, and profiling tools |
  348. ## License
  349. Licensed under either of the following, at your option:
  350. - [Apache License, Version 2.0](LICENSE-APACHE)
  351. - [MIT License](LICENSE-MIT)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.