[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_129":130},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","morluto","moduleId","leantoken","@morluto/leantoken","displayName","LeanToken","tagline","Token-bounded repository context for coding agents over MCP.","iconKey","https://avatars.githubusercontent.com/u/76467478?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1785645248000,"updatedAt",1788160273000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.morluto%2Fleantoken","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",23,"upstreamUpdatedAt",1788154333000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/morluto/leantoken","githubRepoFullName","morluto/leantoken","releaseId","ext-morluto-leantoken","version","0.1.28","descriptionMarkdown","

\n\n

LeanToken

\n\n**Code intelligence for agents: find the code that matters and keep your context window and tokens lean.**\n\n**Language:** English · [简体中文](https://github.com/morluto/leantoken/blob/main/docs/i18n/zh-CN/README.md) · [日本語](https://github.com/morluto/leantoken/blob/main/docs/i18n/ja-JP/README.md) · [한국어](https://github.com/morluto/leantoken/blob/main/docs/i18n/ko-KR/README.md)\n\n- MCP Registry name: `mcp-name: io.github.morluto/leantoken`\n\n $\"LeanToken$ \n\n[![npm](https://img.shields.io/npm/v/leantoken?logo=npm&label=npm)](https://www.npmjs.com/package/leantoken)\n[![npm downloads](https://img.shields.io/npm/dm/leantoken?logo=npm&label=downloads)](https://www.npmjs.com/package/leantoken)\n[![Rust 1.95+](https://img.shields.io/badge/Rust-1.95%2B-000000?logo=rust)](https://www.rust-lang.org/)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](#license)\n\n[Install](#quick-start) · [Why LeanToken](#why-leantoken) · [Tools](#available-tools) · [CLI](#cli-usage) · [How it works](#how-it-works) · [Docs](#documentation)\n\n

\n\n---\n\n> **Measured token savings:** In a controlled 60-run study, LeanToken used\n> 20.1% fewer model input tokens than the agent's built-in tools with limited\n> repository exploration, and 37.6% fewer than those tools with broad\n> exploration. See exactly\n> how it was measured in the [measurement methodology](https://github.com/morluto/leantoken/blob/main/docs/measurement.md).\n\n## Quick start\n\nAdd LeanToken to Claude Code, Cursor, OpenCode, Codex, Gemini CLI, or\nAntigravity:\n\n```bash\nnpx leantoken setup\n```\n\n

Setup behavior and safety

\n\nCurrent releases stop setup before writing when `npx` resolves a stale\nproject-local or ancestor install, and point to\n`npx leantoken@latest setup`. Older releases that predate this check can be\nbootstrapped directly with that versioned command.\n\nThe interactive setup wizard preselects supported clients it detects; you can\nchange that selection before continuing. It then shows the exact configuration\npaths and MCP launcher and asks for a separate final confirmation. Automation\nnever treats detection as consent. An npx-based setup pins the exact LeanToken\nversion that ran setup, so restarting a client cannot silently move to a newer\nrelease.\n\nGlobal setup never stores the repository where setup happened. OpenCode gets a\nworkspace-relative working directory; other supported clients launch LeanToken\nfrom the workspace cwd selected by the host. If a host instead starts it from\nthe home directory or a filesystem root, LeanToken refuses to index that broad\nroot by default.\n\n

\n\nRestart or reload the configured clients, then verify the connection and first\nretrieval from a repository:\n\n```bash\nnpx leantoken doctor\n```\n\nTry a broad task such as: *Find the code related to request cancellation before\nediting.* LeanToken helps the agent start with `leantoken.context`, while its\nnormal tools remain available for edits, builds, and tests.\n\nInspect LeanToken's observed repository-local token accounting:\n\n```bash\nnpx leantoken savings\n```\n\n\n\n\n\n\n\n

\nLocal by default

\nSource is indexed on your machine in a local database. LeanToken is a read-only\ndiscovery and retrieval layer.\n

\nExplicit token budgets

\nEvery response has an explicit token limit, so large files cannot take over the\nrequest.\n

\nBuilt for agent workflows

\nFind files, search code, inspect structure, read exact ranges, trace history,\nquery JSON, and track token usage through focused tools.\n

\n\n

Advanced setup and version management

\n\nTo skip the wizard, select clients explicitly or configure all supported\nclients:\n\n```bash\nnpx leantoken setup --claude --codex --yes\nnpx leantoken setup --all --yes\n```\n\nFor regular use, `--private-runtime` is the recommended launcher: it copies the\nexact package-native executable into LeanToken's versioned application-data\ndirectory so clients launch one verified process directly, without persistent\nnpm/Node wrappers. It remains opt-in so the zero-install path does not add an\napplication-data write. Preview its path and digest with `--dry-run`.\n\nAutomation never treats detection as consent: `--yes` requires explicit client\nflags, `--all`, or `--refresh` for entries already managed by LeanToken. Preview\nthe same resolved plan without changing files:\n\n```bash\nnpx leantoken setup --codex --cursor --dry-run\n```\n\nSetup adds the `leantoken` MCP entry plus a small owned discovery skill only in\nthe directories used by the selected hosts: Claude Code uses `~/.claude`, while\nCodex and the other supported hosts use `~/.agents`. The skill advertises\nrouting metadata; it does not duplicate tool schemas, add rules, or install\nshell hooks. Setup marks new MCP launchers as managed and refuses to replace a\nsame-name manual entry unless you review the dry-run and pass\n`--force-unmanaged`. Remove the owned integration with:\n\n```bash\nnpx leantoken remove\n```\n\nAfter private-runtime upgrades, inspect retained versions and preview a\nreference-safe cleanup before applying it:\n\n```bash\nnpx leantoken runtime list\nnpx leantoken runtime prune --dry-run\nnpx leantoken runtime prune --yes\n```\n\nRefresh only existing LeanToken MCP entries after explicitly choosing a new\nversion, or use an older version to roll back:\n\n```bash\nnpx --yes leantoken@latest setup --refresh --yes\nnpx --yes leantoken@0.1.8 setup --refresh --yes --allow-outdated\n```\n\n

\n\n## Common agent workflows\n\nLeanToken works best as a small evidence loop rather than a one-shot repository\ndump:\n\n1. **Orient autonomous triage in one call.** Start an uncertain broad task with\n `context` and `plan_only: false`, then use the materialized evidence\n directly. Make at most one focused follow-up only when coverage identifies a\n concrete missing implementation or regression-test owner.\n2. **Continue without resending source.** Pass the prior `receipt_id` on the\n next context call, or pass returned fragment hashes as `known_hashes`. The\n response reports exact and overlapping omissions instead of silently\n charging the same evidence again.\n3. **Investigate an observed failure.** Use the `investigation` workflow and\n provide only directly observed `failure_traces`, paths, symbols, or test\n intent in `workflow_evidence`. Follow with exact `search`, `outline`, or\n `read` calls for the owners the evidence identifies.\n4. **Review a change.** Use the `review` workflow with `base_revision` set to\n `BASE..HEAD` and `strict_changed_paths: true`. Request a `handoff` when\n another agent needs a compact manifest of selected hashes, changed paths,\n assumptions, and completed validations without copied source bodies.\n\nThis one-call contract is for autonomous repository triage, not a limit on\nimplementation agents. Human review and control-plane flows can still preview\nexpensive or high-risk retrieval with `plan_only: true` before materializing.\nThe [repeated multi-agent context suite](https://github.com/morluto/leantoken/blob/main/docs/measurement.md#repeated-multi-agent-context-suite)\nfound that an iterative LeanToken profile used 50.9% more total input than thin\nnative, while the frozen one-context-plus-optional-one-search profile saved\n20.1% and had 15/20 path-set successes. Those results cover four pinned triage\ntasks; they do not prove a universal implementation workflow.\n\nExplicit focus constraints are contracts. When a request supplies\n`focus_paths`, exact `focus_symbols`, and\n`minimum_fragments_per_focus_path`, LeanToken generates candidates within the\ndocumented per-file bounds and reports a coverage failure when distinct ranges\ncannot satisfy the minimum. Explain-profile plans and materialized responses\nalso identify the bounded allocation boundary that generated, reserved,\nselected, or suppressed each focus candidate without changing ranking.\n\n## Why LeanToken\n\nMost agents start by searching widely and reading whole files. LeanToken narrows\nthat work in stages:\n\n| Typical repository exploration | With LeanToken |\n| --- | --- |\n| Scan broad directory listings | Find relevant paths in a compact tree |\n| Read whole files to find structure | See definitions and imports without loading the entire file |\n| Send the same code again after each turn | Avoid repeating unchanged evidence |\n| Let large files fill the request | Keep returned source within an exact source-token budget and report response overhead separately |\n| Guess which files matter | Rank likely relevant code for the task |\n\nYour coding agent still handles editing, commands, tests, and conversation.\nLeanToken finds and returns the code those tasks need.\n\nLeanToken does not create one giant prompt file. It answers focused searches and\nreads as the agent needs them.\n\n### Example\n\nFor a task like *fix request cancellation during shutdown*, an illustrative\nbounded result might look like this:\n\n```text\nBudget: 1,200 source tokens\n\nSelected evidence:\n src/services/executor.rs lines 137-147, 251-259\n src/services/reconciliation.rs lines 148-175, 257-272\n```\n\nThe agent receives these ranges instead of both full files. If the budget is too\nsmall, the response also says what was left out. Paths, scores, receipts, JSON,\nand MCP transport wrappers are not part of this source-token budget; see\n[token accounting](https://github.com/morluto/leantoken/blob/main/docs/usage.md#token-accounting) for the measured boundaries.\n\n## Available tools\n\n| Tool | Purpose |\n| --- | --- |\n| `leantoken.context` | Default materialized first call for autonomous broad triage; optional preview for human or control-plane review. |\n| `leantoken.search` | Prefer over grep/rg for ranked search; exhaustive text/regex calls can explicitly record or reuse complete query coverage. |\n| `leantoken.files` | Prefer over find/ls/glob for compact, ignore-aware path discovery. |\n| `leantoken.outline` | Inspect definitions, signatures, imports, and ranges without whole-file reads. |\n| `leantoken.read` | Prefer over cat/head/sed for one exact symbol or inclusive line range. |\n| `leantoken.history` | Read, batch-diff, or trace parsed symbols across immutable Git revisions. |\n| `leantoken.json` | Query, summarize, or compare bounded live JSON with paged keys and typed diagnostics. |\n| `leantoken.receipt_rebase` | Explicitly carry only same-path, same-coordinate, same-hash evidence into a newer completed generation. |\n| `leantoken.savings` | Report observed response accounting, hash suppression, failures, and explicit observation limits. |\n\n

Advanced retrieval controls

\n\nEvery index-backed retrieval tool, including `receipt_rebase`, accepts\n`consistency: \"reconcile_working_tree\"` when completed edits must be reconciled\nbefore the query. The default,\n`\"indexed_generation\"`, returns the latest completed index generation without\nscanning or waiting for filesystem changes; it is not a Git revision boundary.\n`leantoken.history` reads immutable Git objects and `leantoken.json` reads exact\nlive files, so neither accepts an index consistency mode. To constrain context\nto immutable history, pass `BASE..HEAD` as `leantoken.context.base_revision`\nwith `strict_changed_paths: true`.\n\nFor autonomous broad triage, set `plan_only: false` and use the materialized\nevidence directly. Reserve `plan_only: true` for human or control-plane review\nbefore expensive or high-risk retrieval: it returns bounded ranked candidate\nmetadata without source fragments or receipt mutation. After approval, repeat\nthe same request with `plan_only: false`. Set `response_profile: \"compact\"` for\nthe smallest fail-loud response, keep the default `\"balanced\"` shape, or use\n`\"explain\"` for bounded individual omissions, facets, and diff evidence. The\nresponse reports the resolved choice as `effective_response_profile`.\n\n

\n\nThe catalog stays intentionally small because every tool description and\nschema also consumes model context.\n\n## CLI usage\n\nRun LeanToken directly through `npx`:\n\n```bash\nnpx leantoken status\nnpx leantoken savings\nnpx leantoken doctor\nnpx leantoken --root /path/to/repo search handle_request\n```\n\nOr use a globally installed binary:\n\n```bash\nnpm install --global leantoken@latest\n\nleantoken --root /path/to/repo index\nleantoken --root /path/to/repo search handle_request --mode identifier --max-tokens 800\nleantoken --root /path/to/repo context \\\n --task \"fix request cancellation during shutdown\" \\\n --budget 2000\n```\n\nAudit an existing redacted experiment or host report without opening a\nrepository index:\n\n```bash\nleantoken episode audit \\\n --adapter multi-agent-suite-v1 \\\n --input benchmarks/reports/multi-agent-context-suite-v1-codex-0.144.1.json\n```\n\nThe default projection is Markdown; add global `--json` for the stable\nnormalized JSON schema. The auditor is local, bounded, and read-only with\nrespect to its input. It retains artifact hashes, not raw prompts, source, tool\narguments, or tool outputs.\n\n`npm install leantoken` installs the command in the current project's\n`node_modules/.bin`; it does not add `leantoken` to the shell `PATH`. Invoke a\nproject-local install through `npx leantoken`, a package script, or\n`./node_modules/.bin/leantoken`.\n\nRun the MCP server manually over stdio:\n\n```bash\nleantoken --root /path/to/repo mcp\n```\n\n

Manual MCP client configuration

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

\n\nFor the Cargo distribution, install the published crate and point your MCP\nclient at the resulting executable:\n\n```bash\ncargo install leantoken --version VERSION\nleantoken --root /path/to/repo mcp\n```\n\nThe official MCP Registry entry is `io.github.morluto/leantoken`. Registry\nclients that support Cargo packages can install the matching `leantoken`\nversion and use the `mcp` command shown above.\n\n## Installation options\n\nThe npm package includes native binaries for:\n\n- macOS on ARM64 and x64\n- glibc Linux on ARM64 and x64\n- Windows on x64\n\nInstallation does not run lifecycle scripts or download an executable from a\npostinstall hook. Other targets, including musl Linux, must build from source.\nInstall Rust 1.95 or later and a native C/C++ toolchain, then run:\n\n```bash\ncargo install --locked --git https://github.com/morluto/leantoken leantoken\n```\n\n## Updating\n\nMCP entries created through `npx` stay pinned to the exact LeanToken version\nthat configured them. Update existing client integrations explicitly:\n\n```bash\nnpx --yes leantoken@latest setup --refresh --yes\n```\n\nFor a globally installed CLI or a CLI installed with Cargo:\n\n```bash\nleantoken upgrade --check\nleantoken upgrade --yes\n```\n\n`update` is an alias for `upgrade`. For a project-local npm installation:\n\n```bash\nnpm install leantoken@latest\n```\n\nPinned MCP entries never silently move to `@latest`. If the exact package is not\navailable locally or online, startup fails rather than selecting another version.\nUpdating the CLI does not change existing MCP entries. See the\n[usage guide](https://github.com/morluto/leantoken/blob/main/docs/usage.md) for rollbacks, cache management, and version details.\n\n## Cache management\n\nInspect local repository caches or preview cleanup before applying it:\n\n```bash\nleantoken cache list\nleantoken cache list --summary\nleantoken cache list --incompatible-with-current\nleantoken cache prune --incompatible-with-current\nleantoken cache prune --older-than 30 --dry-run\nleantoken cache prune --max-total-bytes 1073741824 --yes\n```\n\nSee the [usage guide](https://github.com/morluto/leantoken/blob/main/docs/usage.md) for cache states, pagination, and cleanup\nsafety rules.\n\n## How it works\n\n```text\nrepository\n │\n ▼\nfile discovery ──► code structure extraction ──► local search index\n │\n ▼\nagent request ──► ranked / exact retrieval ──► focused code within a token budget\n```\n\nLeanToken indexes source once, then serves compact paths, ranked matches,\nstructural outlines, exact source ranges, and task-specific context. It avoids\nresending unchanged evidence across turns.\n\nDependency-heavy workspaces can opt into a separate, cache-identified\nfirst-party index without changing the default whole-repository behavior:\n\n```bash\nleantoken --index-include 'src/**' --index-include 'tests/**' index\n```\n\nStatus and every retrieval disclose whether the active index is full or\nscoped, so an empty scoped result is never presented as whole-repository\nabsence. See the [usage guide](https://github.com/morluto/leantoken/blob/main/docs/usage.md#indexing-scope) for bounds,\ncache identity, and MCP registration examples.\n\nLeanToken's goal is to return the code an agent needs with fewer input tokens.\n\n## Documentation\n\n| Guide | Contents |\n| --- | --- |\n| [Usage and tool reference](https://github.com/morluto/leantoken/blob/main/docs/usage.md) | Commands, MCP tools, request options, and examples |\n| [Architecture and reliability](https://github.com/morluto/leantoken/blob/main/docs/architecture.md) | Components, data flow, storage, and failure behavior |\n| [Roadmap](https://github.com/morluto/leantoken/blob/main/docs/roadmap.md) | Current direction and planned work |\n| [Development and testing](https://github.com/morluto/leantoken/blob/main/docs/development.md) | Local setup, validation, and release workflow |\n| [Benchmark methodology](https://github.com/morluto/leantoken/blob/main/benchmarks/README.md) | Token-economy measurements and interpretation |\n| [Measurement harnesses](https://github.com/morluto/leantoken/blob/main/docs/measurement.md) | Experiment, wire-cost, and profiling tools |\n\n## License\n\nLicensed under either of the following, at your option:\n\n- [Apache License, Version 2.0](https://github.com/morluto/leantoken/blob/main/LICENSE-APACHE)\n- [MIT License](https://github.com/morluto/leantoken/blob/main/LICENSE-MIT)\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":-5,"_118":119},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ai-coding","code-intelligence","code-navigation","code-retrieval","code-search","codebase-indexing","coding-agents","context-engineering","context-window","cordis","dsh","dsh-plugin","rust","token-budget","token-counting","topics",[94,95,96,97,98,99,100,101,102,103,104,105,124,125,126,106,107,108,127,128],"license","Apache-2.0","language","Rust","registryName","io.github.morluto/leantoken","homepage","packages",[120],{"_121":122,"_123":21,"_71":72},"registryType","cargo","identifier","mcp","mcp-server","model-context-protocol","token-efficient","tree-sitter","ENV",{"_131":132,"_133":134,"_135":136},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]