token-pilot 0.24.0 → 0.24.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +35 -0
- package/README.md +76 -14
- package/dist/agents/tp-api-surface-tracker.md +1 -1
- package/dist/agents/tp-audit-scanner.md +1 -1
- package/dist/agents/tp-commit-writer.md +1 -1
- package/dist/agents/tp-dead-code-finder.md +1 -1
- package/dist/agents/tp-debugger.md +1 -1
- package/dist/agents/tp-dep-health.md +1 -1
- package/dist/agents/tp-history-explorer.md +1 -1
- package/dist/agents/tp-impact-analyzer.md +1 -1
- package/dist/agents/tp-incident-timeline.md +1 -1
- package/dist/agents/tp-migration-scout.md +1 -1
- package/dist/agents/tp-onboard.md +1 -1
- package/dist/agents/tp-pr-reviewer.md +1 -1
- package/dist/agents/tp-refactor-planner.md +1 -1
- package/dist/agents/tp-review-impact.md +1 -1
- package/dist/agents/tp-run.md +1 -1
- package/dist/agents/tp-session-restorer.md +1 -1
- package/dist/agents/tp-test-coverage-gapper.md +1 -1
- package/dist/agents/tp-test-triage.md +1 -1
- package/dist/agents/tp-test-writer.md +1 -1
- package/dist/handlers/read-symbols.js +26 -13
- package/docs/token-pilot-dir.md +61 -0
- package/package.json +2 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "token-pilot",
|
|
3
|
-
"version": "0.24.
|
|
3
|
+
"version": "0.24.2",
|
|
4
4
|
"description": "Enforcement layer for token-efficient AI coding: MCP-first hook with structural denial summaries, SessionStart reminder, bless-agents CLI, and six tp-* subagents — works for every agent including those without MCP access.",
|
|
5
5
|
"author": "token-pilot",
|
|
6
6
|
"license": "MIT",
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,41 @@ All notable changes to Token Pilot will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.24.2] - 2026-04-18
|
|
9
|
+
|
|
10
|
+
### Changed — README manual-install section restored and expanded
|
|
11
|
+
|
|
12
|
+
In v0.20.2 I collapsed "Manual install" under a `<details>` to keep the README slim. That was overcorrection: users on Cursor / Codex / Cline / CI / team-shared configs had no quick "how do I add the MCP server?" answer visible.
|
|
13
|
+
|
|
14
|
+
Restored the section as a proper `## Manual MCP install` heading with **per-client examples**:
|
|
15
|
+
|
|
16
|
+
- **Claude Code** — both `claude mcp add` CLI and direct `.mcp.json` edit
|
|
17
|
+
- **Cursor** — `.cursor/mcp.json` example
|
|
18
|
+
- **Codex CLI** — `~/.codex/config.toml` TOML stanza
|
|
19
|
+
- **Cline (VS Code)** — `cline_mcp_settings.json` example
|
|
20
|
+
- **Any MCP-compatible client** — generic `command + args` pattern
|
|
21
|
+
- **Subagents install** (Claude-Code-only) — scope flags + `--force`
|
|
22
|
+
- **From source** — for contributors / vendored installs
|
|
23
|
+
|
|
24
|
+
Also added an env-var table (`TOKEN_PILOT_DENY_THRESHOLD`, `TOKEN_PILOT_ADAPTIVE_THRESHOLD`, `TOKEN_PILOT_BYPASS`, `TOKEN_PILOT_SKIP_POSTINSTALL`) — these used to be scattered across the codebase with no single reference.
|
|
25
|
+
|
|
26
|
+
Docs-only change. No code / test changes. 911 tests still green.
|
|
27
|
+
|
|
28
|
+
## [0.24.1] - 2026-04-18
|
|
29
|
+
|
|
30
|
+
### Fixed — two findings from v0.23.6 field verification
|
|
31
|
+
|
|
32
|
+
**1. `read_symbols` guard missed on real Vue / TS files.** The field report showed a 6-symbols-from-6-exports request where the v0.23.6 guard failed to trip. Root cause: the guard used `sum(lineCount) / fileLines ≥ 0.7`, but ast-index's parser returns **overlapping ranges** on arrow functions / `export function` / Vue SFCs / TypeScript type-vs-function — so `sum(lineCount)` gets inflated past the file size and ratios become meaningless. Switched to a **count-based** guard: if ≥ 3 symbols AND ≥ 70% of the file's top-level symbol count, refuse and advise `smart_read`. Immune to parser line-range bugs.
|
|
33
|
+
|
|
34
|
+
**2. `docs/token-pilot-dir.md` was not shipped in the npm package.** I added the file in v0.23.6 but forgot the `docs/*.md` glob in `package.json` `files:`. Now included.
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **Parser-overlap warning.** If the handler sees `sum(symbol.lineCount) > file.lineCount × 1.5` (definite parser mis-parse — symbols claiming more lines than the file has), it logs one stderr warning pointing at the upstream `defendend/Claude-ast-index-search` issue tracker. Doesn't fail the request; gives users a signal when ast-index is the real culprit for weird results.
|
|
39
|
+
|
|
40
|
+
### Numbers
|
|
41
|
+
- 911 tests green (+1 regression test for overlapping-ranges guard), `tsc --noEmit` clean.
|
|
42
|
+
|
|
8
43
|
## [0.24.0] - 2026-04-18
|
|
9
44
|
|
|
10
45
|
### Added — Tier 3 combo-agents (TP-z64 delivered)
|
package/README.md
CHANGED
|
@@ -46,10 +46,35 @@ This does two things:
|
|
|
46
46
|
|
|
47
47
|
Restart your AI assistant to activate. The Read hook auto-installs the first time `token-pilot` starts inside Claude Code. Works with **Claude Code, Cursor, Codex, Antigravity, Cline**, and any MCP-compatible client.
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
<summary>Manual install (other MCP clients, from source, scripted CI)</summary>
|
|
49
|
+
## Manual MCP install (per-client examples)
|
|
51
50
|
|
|
52
|
-
|
|
51
|
+
If `init` isn't right for your setup — CI, non-TTY environments, editing a shared team config, or a client without an interactive installer — add Token Pilot as an MCP server directly. The server command is `npx -y token-pilot` on every client; only the config file shape differs.
|
|
52
|
+
|
|
53
|
+
### Claude Code
|
|
54
|
+
|
|
55
|
+
Two equivalent paths:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Via CLI (recommended — handles scope + scoping)
|
|
59
|
+
claude mcp add token-pilot -- npx -y token-pilot
|
|
60
|
+
claude mcp add --scope user token-pilot -- npx -y token-pilot
|
|
61
|
+
claude mcp add --scope project token-pilot -- npx -y token-pilot
|
|
62
|
+
|
|
63
|
+
# Or edit .mcp.json directly (project-level) / ~/.mcp.json (user-level)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"token-pilot": { "command": "npx", "args": ["-y", "token-pilot"] },
|
|
70
|
+
"context-mode": { "command": "npx", "args": ["-y", "claude-context-mode"] }
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Cursor
|
|
76
|
+
|
|
77
|
+
Cursor reads `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
|
|
53
78
|
|
|
54
79
|
```json
|
|
55
80
|
{
|
|
@@ -59,27 +84,64 @@ Add to your `.mcp.json`:
|
|
|
59
84
|
}
|
|
60
85
|
```
|
|
61
86
|
|
|
62
|
-
|
|
87
|
+
### Codex CLI
|
|
63
88
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
89
|
+
Codex reads `~/.codex/config.toml`:
|
|
90
|
+
|
|
91
|
+
```toml
|
|
92
|
+
[mcp_servers.token-pilot]
|
|
93
|
+
command = "npx"
|
|
94
|
+
args = ["-y", "token-pilot"]
|
|
67
95
|
```
|
|
68
96
|
|
|
69
|
-
|
|
97
|
+
### Cline (VS Code)
|
|
98
|
+
|
|
99
|
+
Cline reads `cline_mcp_settings.json` (accessible via Cline panel → MCP Servers → Edit):
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"token-pilot": { "command": "npx", "args": ["-y", "token-pilot"] }
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Any MCP-compatible client
|
|
110
|
+
|
|
111
|
+
Use the generic MCP protocol — the server is a plain stdio process:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
command: npx
|
|
115
|
+
args: -y token-pilot
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
No env vars required. Optional overrides:
|
|
119
|
+
|
|
120
|
+
| Env var | Default | Purpose |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| `TOKEN_PILOT_DENY_THRESHOLD` | `300` | Line count above which the Read hook intervenes |
|
|
123
|
+
| `TOKEN_PILOT_ADAPTIVE_THRESHOLD` | `false` | Enable the adaptive curve as the session burns |
|
|
124
|
+
| `TOKEN_PILOT_BYPASS` | unset | Set to `1` to disable the Read hook for one session |
|
|
125
|
+
| `TOKEN_PILOT_SKIP_POSTINSTALL` | unset | Skip the `ast-index` safety-net install at `npm install` time |
|
|
126
|
+
|
|
127
|
+
### Subagents (Claude Code only)
|
|
128
|
+
|
|
129
|
+
`tp-*` subagents are a Claude Code feature. Other clients use only the MCP tools + Read hook. To install on a target scope explicitly:
|
|
70
130
|
|
|
71
131
|
```bash
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
#
|
|
132
|
+
npx token-pilot install-agents --scope=user # all projects
|
|
133
|
+
npx token-pilot install-agents --scope=project # this repo only
|
|
134
|
+
npx token-pilot install-agents --scope=user --force # re-apply after an update
|
|
75
135
|
```
|
|
76
136
|
|
|
77
|
-
|
|
137
|
+
### From source (contributors / vendored installs)
|
|
78
138
|
|
|
79
139
|
```bash
|
|
80
|
-
|
|
140
|
+
git clone https://github.com/Digital-Threads/token-pilot.git
|
|
141
|
+
cd token-pilot && npm install && npm run build
|
|
142
|
+
# Point your client's config at dist/index.js:
|
|
143
|
+
# "command": "node", "args": ["/abs/path/to/token-pilot/dist/index.js"]
|
|
81
144
|
```
|
|
82
|
-
</details>
|
|
83
145
|
|
|
84
146
|
## Modes
|
|
85
147
|
|
|
@@ -10,7 +10,7 @@ tools:
|
|
|
10
10
|
- mcp__token-pilot__smart_read
|
|
11
11
|
- mcp__token-pilot__smart_read_many
|
|
12
12
|
- mcp__token-pilot__read_section
|
|
13
|
-
token_pilot_version: "0.24.
|
|
13
|
+
token_pilot_version: "0.24.2"
|
|
14
14
|
token_pilot_body_hash: ae0b86eaffaf34bf283b94b5572481fa8c2d6a2a25193f1173b70bef0fbe1919
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -7,7 +7,7 @@ tools:
|
|
|
7
7
|
- mcp__token-pilot__read_diff
|
|
8
8
|
- mcp__token-pilot__outline
|
|
9
9
|
- mcp__token-pilot__read_symbol
|
|
10
|
-
token_pilot_version: "0.24.
|
|
10
|
+
token_pilot_version: "0.24.2"
|
|
11
11
|
token_pilot_body_hash: a058518619fd6e2def0c9226f6c70438a5e0a80efe680c935414ecd7e1b14a4f
|
|
12
12
|
---
|
|
13
13
|
|
package/dist/agents/tp-run.md
CHANGED
|
@@ -7,7 +7,7 @@ tools:
|
|
|
7
7
|
- mcp__token-pilot__read_range
|
|
8
8
|
- mcp__token-pilot__find_usages
|
|
9
9
|
- mcp__token-pilot__read_symbol
|
|
10
|
-
token_pilot_version: "0.24.
|
|
10
|
+
token_pilot_version: "0.24.2"
|
|
11
11
|
token_pilot_body_hash: 255912c47661d203c8f9a735237bc419f97e937f788a01811bbe126ee3dd5878
|
|
12
12
|
---
|
|
13
13
|
|
|
@@ -21,22 +21,22 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
|
|
|
21
21
|
}
|
|
22
22
|
const N = args.symbols.length;
|
|
23
23
|
const sections = [];
|
|
24
|
-
// v0.
|
|
25
|
-
//
|
|
26
|
-
//
|
|
27
|
-
//
|
|
28
|
-
|
|
24
|
+
// v0.24.1 — anti-pattern guard. When the caller requests most of the
|
|
25
|
+
// symbols in the file, a batch read costs more than one smart_read.
|
|
26
|
+
// Earlier versions used sum(lineCount), but ast-index parser bugs
|
|
27
|
+
// (arrow functions / export function / Vue SFC / TS types) return
|
|
28
|
+
// overlapping ranges that inflate the sum and let the guard miss. The
|
|
29
|
+
// count-based check (requested symbols / total top-level symbols) is
|
|
30
|
+
// immune to those parser issues.
|
|
31
|
+
if (structure && structure.symbols && structure.symbols.length >= 3) {
|
|
29
32
|
const uniqueRequested = new Set(args.symbols.map((s) => s.split(".")[0]));
|
|
30
33
|
const matchedTopLevel = structure.symbols.filter((s) => uniqueRequested.has(s.name));
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
if (totalTopLevelLines > 0 &&
|
|
34
|
-
requestedLines / totalTopLevelLines >= 0.7 &&
|
|
35
|
-
matchedTopLevel.length >= 3) {
|
|
34
|
+
const total = structure.symbols.length;
|
|
35
|
+
if (matchedTopLevel.length >= 3 && matchedTopLevel.length / total >= 0.7) {
|
|
36
36
|
const text = `FILE: ${args.path} | SYMBOLS: ${N} requested\n\n` +
|
|
37
|
-
`ADVISORY: You requested ${matchedTopLevel.length} symbols
|
|
38
|
-
|
|
39
|
-
`
|
|
37
|
+
`ADVISORY: You requested ${matchedTopLevel.length}/${total} symbols ` +
|
|
38
|
+
`(≥70% of the file's top-level symbols). A batch read here costs ` +
|
|
39
|
+
`more than reading the whole file once.\n\n` +
|
|
40
40
|
`Cheaper alternatives:\n` +
|
|
41
41
|
` - smart_read("${args.path}") for a structural overview\n` +
|
|
42
42
|
` - read_for_edit("${args.path}", "<symbol>") when you need exact edit context\n` +
|
|
@@ -45,6 +45,19 @@ export async function handleReadSymbols(args, projectRoot, symbolResolver, fileC
|
|
|
45
45
|
`or use raw Read (bounded).`;
|
|
46
46
|
return { content: [{ type: "text", text }] };
|
|
47
47
|
}
|
|
48
|
+
// v0.24.1 — sanity-check for parser-produced overlapping ranges. When
|
|
49
|
+
// the sum of symbol lineCounts exceeds the actual file line count by
|
|
50
|
+
// >1.5× we're almost certainly seeing ast-index getting confused by
|
|
51
|
+
// arrow functions / Vue SFCs / type-vs-function. Log once so users
|
|
52
|
+
// can report upstream; don't fail the request.
|
|
53
|
+
const totalSymbolLines = structure.symbols.reduce((sum, s) => sum + (s.location.lineCount ?? 0), 0);
|
|
54
|
+
const fileLines = lines.length;
|
|
55
|
+
if (fileLines > 0 && totalSymbolLines > fileLines * 1.5) {
|
|
56
|
+
process.stderr.write(`[token-pilot] ast-index parser produced overlapping symbol ranges for ${args.path} ` +
|
|
57
|
+
`(sum=${totalSymbolLines} lines vs file=${fileLines}). ` +
|
|
58
|
+
`Results may mis-classify symbols; consider smart_read + read_for_edit instead. ` +
|
|
59
|
+
`Upstream issue: https://github.com/defendend/Claude-ast-index-search/issues\n`);
|
|
60
|
+
}
|
|
48
61
|
}
|
|
49
62
|
// Show mode constants (same as read_symbol.ts)
|
|
50
63
|
const MAX_SYMBOL_LINES = 300;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# `.token-pilot/` directory layout
|
|
2
|
+
|
|
3
|
+
Token Pilot writes state and telemetry to a `.token-pilot/` directory in your project root. Nothing is created eagerly — each sub-path appears only when a feature that needs it fires for the first time. Committing the directory is optional; most users add it to `.gitignore`.
|
|
4
|
+
|
|
5
|
+
## Files & directories
|
|
6
|
+
|
|
7
|
+
| Path | Who writes | When it appears | Purpose | Commit? |
|
|
8
|
+
|---|---|---|---|---|
|
|
9
|
+
| `hook-events.jsonl` | Read hook | First `Read` of a code file ≥ the `denyThreshold` | JSONL telemetry — one entry per hook decision (denied / allowed / bypass). Read by `session_analytics` and the adaptive-threshold logic. Auto-rotates at 10 MB, keeps 30-day history with 100 MB total cap. | **No** |
|
|
10
|
+
| `hook-denied.jsonl` | Read hook (legacy) | Historical, from before v0.20 | Older-format event log kept for backward compatibility with pre-v0.20 `loadDeniedReads()` readers. Safe to delete. | No |
|
|
11
|
+
| `snapshots/` | `session_snapshot` MCP tool | First call to `session_snapshot` | Archived + `latest.md` copy of each snapshot. Retention: last 10 archives. Surfaced by the SessionStart hook when `latest.md` is < 2h old. | Optional — commit `latest.md` if you want a next-session pointer to persist across clones |
|
|
12
|
+
| `context-registries/<session-id>.json` | MCP server | First dedup-aware tool call (`smart_read`, `read_symbol`, `read_range`, `smart_read_many`) with a `session_id` arg | Per-session dedup state — what was loaded, content hashes, load times. LRU cap 8 sessions in memory; older ones live only on disk. | **No** — session-local |
|
|
13
|
+
| `docs/<name>.md` | `token-pilot save-doc` CLI | Explicit user invocation | User-saved research / notes (curl output, WebFetch, long paste) that should survive compaction. Read back cheaply with `smart_read` / `read_range`. | Optional — commit if the doc is team-wide knowledge |
|
|
14
|
+
| `over-budget.log` | PostToolUse:Task hook | First time a `tp-*` subagent exceeds its frontmatter budget by > 10 % | JSONL audit trail for budget overages. Used by future `session_analytics` views. Empty file means no overages so far — good. | **No** |
|
|
15
|
+
| `tp-refactor-planner-<timestamp>.md` | `tp-refactor-planner` agent | Only when the agent's plan exceeds its response budget | Full step list spilled from the agent's response when it would have exceeded ~500 tokens inline. Response in chat points at this file. | Usually **no** — review and delete after the refactor lands |
|
|
16
|
+
|
|
17
|
+
## Quick rules
|
|
18
|
+
|
|
19
|
+
- **Nothing appears until you use it.** If you only ever ran the Read hook, only `hook-events.jsonl` will exist.
|
|
20
|
+
- **Safe to delete the whole folder** — everything rebuilds from the next tool call. You'll lose: dedup memory, snapshot history, saved research. You'll keep: installed hooks, agents, configs (those live elsewhere).
|
|
21
|
+
- **Add to `.gitignore`** unless your team uses snapshots or saved-docs as shared context.
|
|
22
|
+
|
|
23
|
+
Recommended `.gitignore` stanza:
|
|
24
|
+
|
|
25
|
+
```gitignore
|
|
26
|
+
# Token Pilot — session-local telemetry & state
|
|
27
|
+
.token-pilot/hook-events*.jsonl
|
|
28
|
+
.token-pilot/hook-denied.jsonl
|
|
29
|
+
.token-pilot/context-registries/
|
|
30
|
+
.token-pilot/over-budget.log
|
|
31
|
+
.token-pilot/tp-refactor-planner-*.md
|
|
32
|
+
|
|
33
|
+
# Keep these if you want shared snapshots / notes:
|
|
34
|
+
# !.token-pilot/snapshots/latest.md
|
|
35
|
+
# !.token-pilot/docs/
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Inspecting live state
|
|
39
|
+
|
|
40
|
+
Useful one-liners to audit a session in progress:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# How many hook events this session
|
|
44
|
+
wc -l .token-pilot/hook-events.jsonl
|
|
45
|
+
|
|
46
|
+
# Token savings so far (sum of savedTokens)
|
|
47
|
+
cat .token-pilot/hook-events.jsonl | python3 -c "
|
|
48
|
+
import sys, json
|
|
49
|
+
print(sum(json.loads(l).get('savedTokens', 0) for l in sys.stdin if l.strip()))"
|
|
50
|
+
|
|
51
|
+
# Any subagent blew its budget?
|
|
52
|
+
cat .token-pilot/over-budget.log 2>/dev/null || echo "no overages"
|
|
53
|
+
|
|
54
|
+
# Latest session snapshot (if any)
|
|
55
|
+
cat .token-pilot/snapshots/latest.md 2>/dev/null | head -20
|
|
56
|
+
|
|
57
|
+
# What dedup state is persisted
|
|
58
|
+
ls .token-pilot/context-registries/ 2>/dev/null
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Or ask the agent — `mcp__token-pilot__session_analytics` returns the same signals in a structured form.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "token-pilot",
|
|
3
|
-
"version": "0.24.
|
|
3
|
+
"version": "0.24.2",
|
|
4
4
|
"description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"dist/**/*.js",
|
|
12
12
|
"dist/**/*.d.ts",
|
|
13
13
|
"dist/agents/*.md",
|
|
14
|
+
"docs/*.md",
|
|
14
15
|
"scripts/postinstall.mjs",
|
|
15
16
|
"start.sh",
|
|
16
17
|
".claude-plugin/",
|