# io.github.Digital-Threads/token-pilot (npm · token-pilot)

Save up to 80% tokens when AI reads code via AST-aware structural reading

- Trust score: 59/100 (low)
- Change this week: +34
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `token-pilot`: 59/100 (this document), [markdown](https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot.md), [page](https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot)

## Channel facts

- Registry: `npm`
- Package: `token-pilot`
- Version: `0.50.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 83/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (111 of 115), so this covers what we could see, not the whole tree.
  - Runs a script at install time (postinstall) that we could not recognise. It may be perfectly ordinary, but we do not read the published tarball, so we cannot say what it does.
  - Only part of the dependency tree could be resolved (111 of 115), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 7 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 28/100
  - AI-judged instruction clarity (poor).
  - Context-footprint check failed: tool/resource definitions use about 4453 tokens (~178/item across 25 items; 25 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add digital-threads-token-pilot -- npx -y token-pilot
```

### Codex

```bash
codex mcp add digital-threads-token-pilot -- npx -y token-pilot
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "digital-threads-token-pilot": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "token-pilot"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add digital-threads-token-pilot --command npx --arg -y --arg token-pilot
```

### Hermes

```yaml
mcp_servers:
  digital-threads-token-pilot:
    command: "npx"
    args: ["-y", "token-pilot"]
```

### Other

```json
{
  "mcpServers": {
    "digital-threads-token-pilot": {
      "command": "npx",
      "args": [
        "-y",
        "token-pilot"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 59, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 55, +31)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [security] The scripts that run when this package is installed changed: postinstall
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Schema quality: unverified → poor
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional] Licence: MIT

### 2026-08-01 (score 24, −8)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 32, +24)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → partial
- [security] The scripts that run when this package is installed changed: postinstall
- [functional regression] Security disclosure: unverified → fail
- [functional regression] Dependency health: partial → unverified
- [functional improvement] License: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: MIT

### 2026-07-29 (score 8, −17)

- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Dependency health: unverified → partial
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 25)

First indexed and scored.

## MCP tools (25)

### `smart_read` (~280 tokens)

Use INSTEAD OF Read/cat for code files. Returns code structure (classes, functions, methods with signatures and line ranges) — 60-80% fewer tokens than raw content. Use read_symbol() to drill into specific code.

Input parameters:

- `depth` (number): Max depth for nested symbols (default: 2)
- `force` (boolean): Bypass dedup — return full content even if the same path was already loaded earlier in this session. Use when the prior result was compacted out of context.
- `max_tokens` (number): Token budget. If output exceeds this, auto-downgrades: full → outline → compact. Use for context-constrained sessions.
- `path` (string, required): File path (absolute or relative to project root)
- `scope` (string): Output scope: full (default, all details), nav (names + lines only, 2-3x smaller), exports (public API only)
- `session_id` (string): Optional Claude Code session_id. When provided, dedup state (already-loaded files) persists across MCP server restarts and /clear, tied to that session. Omit to use ephemeral process-scoped dedup.
- `show_docs` (boolean): Include doc comments (default: true)
- `show_imports` (boolean): Include import details (default: true)

### `read_symbol` (~205 tokens)

Read source code of ONE specific function/method/class — INSTEAD OF reading the whole file. Supports Class.method syntax.

Input parameters:

- `context_after` (number): Lines of context after (default: 0)
- `context_before` (number): Lines of context before (default: 2)
- `force` (boolean): Bypass dedup (see smart_read.force).
- `include_edit_context` (boolean): Append raw code block for Edit old_string (saves a read_for_edit call)
- `path` (string, required): File path
- `session_id` (string): Optional Claude Code session_id for cross-restart dedup (see smart_read).
- `show` (string): Display mode: full (all lines), head (first 50), tail (last 30), outline (head + methods + tail). Default: auto (full ≤300 lines, outline >300)
- `symbol` (string, required): Symbol name, e.g. "UserService.updateUser"

### `read_symbols` (~194 tokens)

Batch read MULTIPLE symbols from ONE file — saves N-1 round-trips vs calling read_symbol N times. BEST FIT: 3–8 symbols in one file when you need their bodies. For 1–2 symbols use read_symbol (simpler). If you'd request ≥70% of the file's symbols, the handler refuses and points you to smart_read — that's cheaper than a large batch. For edit preparation use read_for_edit.

Input parameters:

- `context_after` (number): Lines of context after each symbol (default: 0)
- `context_before` (number): Lines of context before each symbol (default: 2)
- `path` (string, required): File path
- `show` (string): Display mode for each symbol (default: auto)
- `symbols` (array, required): Array of symbol names (max 10), e.g. ["UserService.create", "UserService.update", "UserService.delete"]

### `read_range` (~109 tokens)

Read a specific line range from a file. Use when you know exact lines — lighter than reading the whole file.

Input parameters:

- `end_line` (number, required): End line (1-indexed, inclusive)
- `force` (boolean): Bypass dedup (see smart_read.force).
- `path` (string, required): File path
- `session_id` (string): Optional Claude Code session_id for cross-restart dedup (see smart_read).
- `start_line` (number, required): Start line (1-indexed)

### `read_section` (~160 tokens)

Read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (rows:1-50). Much cheaper than reading the whole file. DOCS/DATA ONLY — `heading` is required; this does NOT read code by line/symbol. For source files use read_range (line range) or read_symbol (one symbol).

Input parameters:

- `heading` (string, required): Section heading (Markdown), top-level key (YAML/JSON), or row range "rows:1-50" (CSV). Case-insensitive.
- `path` (string, required): Path to .md, .yaml, .yml, .json, or .csv file

### `read_diff` (~71 tokens)

Use INSTEAD OF re-reading whole file after edits. Shows only changed hunks. REQUIRES: call smart_read or read_for_edit BEFORE editing to create baseline snapshot.

Input parameters:

- `context_lines` (number): Lines of context around changes (default: 3)
- `path` (string, required): File path

### `read_for_edit` (~286 tokens)

Use INSTEAD OF Read when preparing an EDIT. Returns exact RAW code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Unlike read_symbols (for reading/understanding), this returns unformatted code optimized for copy-paste into Edit. Optional: include_callers, include_tests, include_changes for enriched context.

Input parameters:

- `context` (number): Lines of context around target (default: 5)
- `include_callers` (boolean): Show top callers of this symbol (saves a separate find_usages call)
- `include_changes` (boolean): Show recent git changes in the target region
- `include_tests` (boolean): Show related test file and test names
- `line` (number): Line number to edit (alternative to symbol)
- `path` (string, required): File path
- `section` (string): Section to edit: heading (Markdown), top-level key (YAML/JSON), or "rows:1-50" (CSV). Returns raw section content for Edit old_string.
- `symbol` (string): Symbol name to edit (e.g. "UserService.updateUser")
- `symbols` (array): Array of symbol names for batch edit context (max 10). Alternative to single "symbol" — returns all symbols in one call.

### `smart_read_many` (~116 tokens)

Batch smart_read for multiple files at once — INSTEAD OF calling Read on each file. Returns structure for each file. Max 20 files.

Input parameters:

- `force` (boolean): Bypass dedup (see smart_read.force).
- `max_tokens` (number): Token budget per file. If a file exceeds this, auto-downgrades to compact outline.
- `paths` (array, required): Array of file paths
- `session_id` (string): Optional Claude Code session_id for cross-restart dedup (see smart_read).

### `find_usages` (~261 tokens)

Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code. HINT: for very short / generic symbols (≤4 chars like `id`, `err`, `Cmd`, `db`) Grep is usually cheaper than find_usages — the semantic grouping doesn't pay off when the symbol resolves ambiguously across thousands of files.

Input parameters:

- `context_lines` (number): Lines of source context around each match (0-10). When set, shows surrounding code — saves follow-up read_symbol calls.
- `kind` (string): Show only specific section (default: "all")
- `lang` (string): Filter by language/extension (e.g., "php", "typescript")
- `limit` (number): Max results per category (default: 50, max: 500)
- `mode` (string): Output mode: full (with context, default), list (file:line only, 5-10x smaller for initial discovery)
- `scope` (string): Filter results by path prefix (e.g., "src/Domain/")
- `symbol` (string, required): Symbol name to find usages of

### `project_overview` (~72 tokens)

START HERE for unfamiliar codebases. Shows project type, architecture, framework detection, quality tools, CI, directory map. Use include filter for specific sections.

Input parameters:

- `include` (array): Sections to include (default: all). Use ["stack"] for quick type check, ["quality","ci"] for tooling overview.

### `related_files` (~65 tokens)

Show ranked import graph for a file: imports, importers, and tests scored by relevance (test adjacency, import closeness, recent changes, path proximity). Files ranked into HIGH VALUE / MEDIUM / LOW to prioritize reading.

Input parameters:

- `path` (string, required): File path to analyze

### `outline` (~96 tokens)

Use INSTEAD OF listing dir + reading each file. One call returns all symbols (classes, functions, methods, routes) for every code file in a directory. Supports recursive with max_depth.

Input parameters:

- `max_depth` (number): Max recursion depth when recursive=true (default: 2, max: 5)
- `path` (string, required): Directory path
- `recursive` (boolean): Recursively outline subdirectories (default: false)

### `session_analytics` (~72 tokens)

Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits. Use verbose=true for full breakdown (per-intent, decision insights, savings by category).

Input parameters:

- `verbose` (boolean): Show detailed breakdown: per-intent, savings by category, decision insights (default: false)

### `call_tree` (~98 tokens)

Recursive depth-N call hierarchy for a function. Shows who calls who transitively — complements find_usages (flat one-level refs) by revealing full chains from leaf helpers to entry points. Use for debugging, refactor impact, and verifying reachability.

Input parameters:

- `depth` (number): Walk-up depth. Default 3, max 6.
- `symbol` (string, required): Function / method name, unqualified (e.g. `fetchUser`).

### `find_unused` (~80 tokens)

Find dead code — functions, classes, and variables with no references across the project. Use for cleanup and refactoring.

Input parameters:

- `export_only` (boolean): Only check exported (capitalized) symbols
- `limit` (number): Max results (default: 30)
- `module` (string): Filter by module path (e.g., "src/services/")

### `code_audit` (~207 tokens)

Find code quality issues: TODO/FIXME comments, deprecated symbols, structural code patterns (bare except:, print() calls). Use for project-wide audits.

Input parameters:

- `check` (string, required): What to check: "pattern" (structural search via ast-grep, e.g. "except:", "print($$$ARGS)"), "todo" (TODO/FIXME comments), "deprecated" (deprecated symbols), "annotations" (find by decorator name), "…
- `lang` (string): Language filter for check="pattern" (e.g., "python", "typescript")
- `limit` (number): Max results (default: 50)
- `name` (string): Decorator/annotation name for check="annotations". Example: "Deprecated", "Controller"
- `pattern` (string): Code pattern for check="pattern". ast-grep syntax: "except:" finds bare excepts, "print($$$ARGS)" finds print calls.

### `module_info` (~106 tokens)

Analyze module dependencies, dependents, public API, and unused deps. Use for architecture understanding and dependency cleanup.

Input parameters:

- `check` (string): What to check: "deps" (dependencies), "dependents" (who depends on this), "api" (public symbols), "unused-deps" (dead dependencies), "all" (everything). Default: "all"
- `module` (string, required): Module name or path pattern (e.g., "auth", "src/Domain/")

### `module_route` (~231 tokens)

Show the transitive dependency path(s) between two modules — how module A reaches module B through the import graph. Use to answer 'how does X depend on Y?', trace coupling, or generate a dependency diagram. format='mermaid'/'dot' emits a diagram; default text lists the hops.

Input parameters:

- `all` (boolean): Show all simple paths instead of just the shortest (default: false)
- `format` (string): Output format: "text" (default, hop listing), "json", "mermaid" or "dot" (dependency diagram)
- `from` (string, required): Source module — the one whose dependencies are followed (name or path, e.g. "auth", "apps/api")
- `maxDepth` (number): Cap on path length in hops (default: 20, max: 50)
- `maxPaths` (number): Cap on number of paths returned (default: 50, max: 200)
- `to` (string, required): Target module to reach
- `viaKind` (string): Restrict traversal to a dependency kind (default: "all")

### `smart_diff` (~104 tokens)

Use INSTEAD OF raw git diff. Shows changed files with AST symbol mapping — which functions/classes were modified/added/removed. Small diffs include hunks, large diffs show summary.

Input parameters:

- `path` (string): Filter to specific file or directory
- `ref` (string): Git ref — required for scope="commit" (commit hash) or scope="branch" (branch name)
- `scope` (string): Diff scope (default: "unstaged")

### `explore_area` (~158 tokens)

One-call exploration of a directory: outline (all symbols), imports (external deps + who imports this area), tests (matching test files), recent git changes. Use INSTEAD OF separate outline + related_files + git log calls. Default since v0.30.0 returns only outline+changes — telemetry showed the all-4 default producing negative token reduction for small areas. Opt into imports/tests explicitly via `include` when you need them.

Input parameters:

- `include` (array): Sections to include. Default: ["outline","changes"]. Add "imports" for dep graph, "tests" to map test files — both can be heavy on large areas.
- `path` (string, required): Directory path (or file path — will use its parent directory)

### `explore` (~167 tokens)

One-shot ranked context + call/inheritance graph blast-radius for a query. Returns ranked symbols, the source heads of the top-ranked files, graph neighbours (callers + subclasses — the blast radius), and related test files in a single compact block. Use INSTEAD OF separate find_usages + read_symbol + call_tree when you need to understand an area fast — cheaper than chaining those three.

Input parameters:

- `graph` (boolean): Include call/inheritance graph neighbours (blast radius). Default: true. Set false to skip the graph walk.
- `max_files` (number): Cap on the number of source file heads returned (default: binary's own limit)
- `query` (string, required): Search terms (the binary splits the string into terms itself), e.g. "AstIndexClient buildIndex"

### `smart_log` (~167 tokens)

Use INSTEAD OF raw git log. Structured commit history with category detection (feat/fix/refactor/docs), file stats, author breakdown. Filters by path and ref. HEADS UP: two verification runs measured this tool at ~39% token reduction (borderline — vs 95-99% for outline/smart_diff). Cumulative data being gathered — tool may be dropped or redesigned in v0.30.0 if numbers don't improve. Prefer scoping with `path` or `count` to tighten savings.

Input parameters:

- `count` (number): Number of commits (default: 10, max: 50)
- `path` (string): Filter to specific file or directory
- `ref` (string): Git ref — branch, tag, or commit (default: HEAD)

### `test_summary` (~120 tokens)

Run tests and return structured summary: total/passed/failed/skipped + failure details. 200 lines of raw output → 10-15 lines. Supports vitest, jest, pytest, phpunit, go test, cargo test.

Input parameters:

- `command` (string, required): Test command to run (e.g., "npm test", "pytest", "go test ./...")
- `runner` (string): Force specific parser (auto-detected if omitted)
- `timeout` (number): Timeout in ms (default: 60000, max: 300000)

### `session_snapshot` (~136 tokens)

Capture current session state as a compact markdown block (<200 tokens). Call before compaction, when switching direction, or periodically in long sessions. Model provides the facts, tool formats them.

Input parameters:

- `blocked` (string): Current blocker or obstacle
- `confirmed` (array): Established facts (what has been verified)
- `decisions` (array): Key decisions made and why (e.g., "removed sysfee step — caused double counting"). Prevents revisiting rejected approaches.
- `files` (array): Relevant file paths
- `goal` (string, required): Session goal — what and why
- `next` (string): Next step to take

### `session_budget` (~101 tokens)

META / info-only: reports Read-hook pressure for this session (suppressed tokens, reference budget, burn fraction, effective denyThreshold). Does NOT save tokens itself — this is diagnostic, use to decide when to tighten before a big read. NOTE: burnFraction measures hook activity, not actual context-window occupancy.

Input parameters:

- `sessionId` (string, required): Claude Code session_id (same id that appears in hook-events.jsonl). Pass "" to read with no session filter.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot#diagnostics

## Score history

- 2026-08-03: 59
- 2026-08-02: 55
- 2026-08-01: 24
- 2026-07-31: 32
- 2026-07-29: 8
- 2026-07-28: 25
- 2026-07-27: 25

## Links

- npm package: https://www.npmjs.com/package/token-pilot
- Socket report: https://socket.dev/npm/package/token-pilot
- Repository: https://github.com/Digital-Threads/token-pilot
- Changelog RSS feed: https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot/changelog.json
- HTML version of this page: https://verifymcp.io/servers/digital-threads-token-pilot/token-pilot