token-pilot 0.28.3 → 0.30.0

package/docs/installation.md

@@ -0,0 +1,143 @@
+# Installation Guide
+
+## Quickest path
+
+```bash
+npx -y token-pilot init
+```
+
+Writes `.mcp.json` (or merges into an existing one), adds `token-pilot` + [`context-mode`](https://github.com/mksglu/claude-context-mode), then prompts to install `tp-*` subagents. Restart your AI assistant to activate.
+
+---
+
+## Claude Code
+
+Three paths — pick one, they're mutually exclusive.
+
+### A. Plugin (one-step: hooks + MCP registered together)
+
+```bash
+claude plugin marketplace add https://github.com/Digital-Threads/token-pilot
+claude plugin install token-pilot@token-pilot
+```
+
+Claude Code clones the repo into `~/.claude/plugins/cache/token-pilot/`, sets `CLAUDE_PLUGIN_ROOT`, and registers the MCP server + all hooks declared in `.claude-plugin/hooks/hooks.json`. No `install-hook` call needed. Run `install-agents` separately for the `tp-*` subagents.
+
+### B. MCP config (npm-based, no plugin system)
+
+```bash
+claude mcp add token-pilot -- npx -y token-pilot
+# or for a specific scope:
+claude mcp add --scope user    token-pilot -- npx -y token-pilot
+claude mcp add --scope project token-pilot -- npx -y token-pilot
+```
+
+Or edit `.mcp.json` (project-level) / `~/.mcp.json` (user-level) directly:
+
+```json
+{
+  "mcpServers": {
+    "token-pilot": { "command": "npx", "args": ["-y", "token-pilot"] },
+    "context-mode": { "command": "npx", "args": ["-y", "claude-context-mode"] }
+  }
+}
+```
+
+Then:
+```bash
+npx token-pilot install-hook                   # register PreToolUse hooks
+npx token-pilot install-agents --scope=user    # install tp-* subagents
+```
+
+### C. One-liner
+
+```bash
+npx -y token-pilot init
+```
+
+Writes path B config for you, then prompts about subagents.
+
+---
+
+## Cursor
+
+Cursor reads `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "token-pilot": { "command": "npx", "args": ["-y", "token-pilot"] }
+  }
+}
+```
+
+---
+
+## Codex CLI
+
+Codex reads `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.token-pilot]
+command = "npx"
+args = ["-y", "token-pilot"]
+```
+
+---
+
+## Cline (VS Code)
+
+Cline reads `cline_mcp_settings.json` (accessible via Cline panel → MCP Servers → Edit):
+
+```json
+{
+  "mcpServers": {
+    "token-pilot": { "command": "npx", "args": ["-y", "token-pilot"] }
+  }
+}
+```
+
+---
+
+## Gemini CLI
+
+Add to `~/.gemini/settings.json` or follow Gemini CLI MCP documentation for your version.
+
+---
+
+## Any MCP-compatible client
+
+The server is a plain stdio process:
+
+```
+command: npx
+args:    -y token-pilot
+```
+
+No env vars required. Common optional overrides:
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `TOKEN_PILOT_MODE` | `deny` | `advisory` / `deny` / `strict` — enforcement level |
+| `TOKEN_PILOT_PROFILE` | `full` | `nav` / `edit` / `full` — trims `tools/list` payload |
+| `TOKEN_PILOT_DENY_THRESHOLD` | `300` | Line count above which the Read hook intervenes |
+| `TOKEN_PILOT_ADAPTIVE_THRESHOLD` | `false` | Enable adaptive curve as session burns |
+| `TOKEN_PILOT_BYPASS` | unset | Set to `1` to disable the Read hook for one session |
+| `TOKEN_PILOT_SKIP_POSTINSTALL` | unset | Skip `ast-index` safety-net install at `npm install` time |
+
+---
+
+## From source (contributors / vendored installs)
+
+```bash
+git clone https://github.com/Digital-Threads/token-pilot.git
+cd token-pilot && npm install && npm run build
+# Point your client's config at dist/index.js:
+#   "command": "node", "args": ["/abs/path/to/token-pilot/dist/index.js"]
+```
+
+---
+
+## Non-Claude clients
+
+`install-agents` detects non-Claude clients via env vars + filesystem markers (`CURSOR_TRACE_ID`, `~/.codex/`, `~/.gemini/`, etc.) and **skips installing subagents** unless you pass `--scope=user|project` explicitly. Cursor, Codex, Gemini, and Cline users get all 22 MCP tools + PreToolUse hooks without the `tp-*` agents.

package/docs/tools.md

@@ -0,0 +1,61 @@
+# MCP Tools Reference
+
+Token Pilot exposes 22 MCP tools. All handlers remain active regardless of [tool profile](configuration.md#tool-profiles) — the profile only trims what appears in `tools/list` at session start.
+
+## Reading
+
+| Tool | Instead of | Purpose |
+|------|-----------|---------|
+| `smart_read` | `Read` | AST outline; 90% fewer tokens on large files |
+| `read_symbol` | `Read` + scroll | One class/function by name (`Class.method` supported) |
+| `read_symbols` | N × `read_symbol` | Batch up to 10 symbols from one file |
+| `read_for_edit` | `Read` before `Edit` | Minimal raw code around a symbol — copy directly as `old_string` |
+| `read_range` | `Read` offset | Specific line range |
+| `read_section` | `Read` | Section by heading (Markdown) or key (YAML/JSON/CSV) |
+| `read_diff` | re-`Read` after edit | Changed hunks since last `smart_read` |
+| `smart_read_many` | multiple `Read` | Batch smart_read for up to 20 files |
+
+## Search & Navigation
+
+| Tool | Instead of | Purpose |
+|------|-----------|---------|
+| `find_usages` | `Grep` (refs) | All usages of a symbol; filters by scope/kind/lang/mode |
+| `project_overview` | `ls` + explore | Project type, frameworks, architecture, directory map |
+| `related_files` | manual | Import graph: imports, importers, test files |
+| `outline` | multiple `smart_read` | Compact symbol overview of all code in a directory |
+| `find_unused` | manual | Dead code detection — unreferenced exported symbols |
+| `code_audit` | multiple `Grep` | TODOs, deprecated symbols, structural patterns |
+| `module_info` | manual | Deps, dependents, public API, unused deps |
+| `smart_diff` | raw `git diff` | Structural diff with symbol mapping |
+| `explore_area` | 3–5 calls | Structure + imports + tests + recent changes in one call |
+| `smart_log` | raw `git log` | Structured commits with category detection |
+| `test_summary` | raw test output | Run tests → pass/fail summary + failure details |
+
+## Session
+
+| Tool | Purpose |
+|------|---------|
+| `session_snapshot` | Compact markdown snapshot (<200 tokens) of goal, decisions, facts, blockers, next step. Auto-persisted to `.token-pilot/snapshots/latest.md`. |
+| `session_budget` | Hook-suppression pressure for this session: saved tokens, burn fraction, effective denyThreshold, time-to-compact projection. |
+| `session_analytics` | Token savings: per-tool breakdown, top files, policy advisories. |
+
+## `find_usages` modes
+
+`find_usages` accepts a `mode` parameter:
+
+| Mode | Output | Tokens |
+|------|--------|--------|
+| `full` | Symbol usages with surrounding code context | ~5–20× more |
+| `list` *(strict default)* | File:line pairs only — 5–10× smaller | smallest |
+
+In `TOKEN_PILOT_MODE=strict`, `mode` defaults to `"list"` when not set by the caller. Pass `mode: "full"` explicitly to override.
+
+## `smart_read` scopes
+
+| Scope | Output |
+|-------|--------|
+| *(default)* | Full AST outline with types, signatures, docs |
+| `nav` | Names + line numbers only (2–3× smaller) |
+| `exports` | Public API surface only |
+
+In `TOKEN_PILOT_MODE=strict`, `max_tokens` defaults to 2 000 when not set by the caller.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "token-pilot",
-  "version": "0.28.3",
-  "description": "Save up to 80% tokens when AI reads code \u2014 MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
+  "version": "0.30.0",
+  "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",
   "type": "module",
   "main": "dist/index.js",
   "bin": {