token-pilot 0.29.0 → 0.30.0

package/docs/hooks.md

@@ -0,0 +1,99 @@
+# Hooks & Enforcement Modes
+
+Token Pilot installs two categories of PreToolUse hooks in Claude Code:
+
+1. **Read hook** — intercepts large `Read` calls (configurable threshold, default 300 lines) and returns a structural summary in the denial reason.
+2. **Grep / Bash hooks** — block heavy recursive patterns (`grep -r`, `find /`, `cat <file.ts>`, unbounded `git log`, bare `git diff`) and redirect to token-pilot MCP equivalents.
+
+## TOKEN_PILOT_MODE — Enforcement Mode
+
+Controls how aggressively both hook categories behave:
+
+| Value | Grep/Bash hooks | MCP output |
+|-------|----------------|------------|
+| `advisory` | Pass all through (no blocking) | No caps |
+| `deny` *(default)* | Block heavy patterns, allow bounded variants | No caps |
+| `strict` | Same as deny, plus auto-cap MCP output (see below) | Capped |
+
+```bash
+# Set in your MCP server env block or shell profile:
+TOKEN_PILOT_MODE=strict npx token-pilot
+```
+
+### Strict-mode MCP output caps
+
+When `TOKEN_PILOT_MODE=strict` and the caller has not set the parameter explicitly:
+
+| Tool | Auto-injected default | Note appended |
+|------|-----------------------|---------------|
+| `smart_read` | `max_tokens: 2000` | Yes |
+| `explore_area` | `include: ["outline"]` | Yes |
+| `find_usages` | `mode: "list"` | Yes |
+| `smart_log` | `count: 20` | Yes |
+
+Pass the parameter explicitly to override the cap.
+
+## Read Hook Modes
+
+The PreToolUse:Read hook has its own mode (separate from enforcement mode). Set in `.token-pilot.json`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `off` | Hook is inert — all `Read` calls pass through |
+| `advisory` | Denies unbounded Read with a short tip pointing at `smart_read` / `read_for_edit` |
+| `deny-enhanced` *(default)* | Denies the Read and returns a full structural summary (imports, exports, declarations) **inside** the denial reason. Works for subagents that lack MCP access. |
+
+```json
+{ "hooks": { "mode": "deny-enhanced", "denyThreshold": 300 } }
+```
+
+## Grep / Bash Hook Rules
+
+The Grep hook redirects symbol-like patterns to `find_usages`. The Bash hook blocks:
+
+| Pattern | Blocked when | Allowed when |
+|---------|-------------|--------------|
+| `grep -r`/`-R` | Always (unbounded) | Has `-m N` bound |
+| `find /`, `find ~` | No `-maxdepth` | Has `-maxdepth N` |
+| `cat <file.ts>` | Code file, no pipeline | In pipeline (`cat … \| head`) or non-code file |
+| `git log` | No count limit | Has `-n N`, `--max-count`, or `\| head` |
+| `git diff` | Bare (no path/flag) | Has path arg or `--stat` |
+| `bash -c "…"`, `eval "…"` | Inner command is heavy | Inner command is benign |
+
+## Installing / Removing Hooks
+
+```bash
+npx token-pilot install-hook      # register PreToolUse hooks in Claude Code
+npx token-pilot uninstall-hook    # remove hooks
+```
+
+Hooks are auto-installed on first server start inside Claude Code. The Claude Code plugin path installs hooks automatically:
+
+```bash
+claude plugin marketplace add https://github.com/Digital-Threads/token-pilot
+claude plugin install token-pilot@token-pilot
+```
+
+## Environment Variables
+
+| Var | Effect |
+|-----|--------|
+| `TOKEN_PILOT_MODE` | `advisory` / `deny` (default) / `strict` — enforcement level for Grep/Bash hooks and MCP output caps |
+| `TOKEN_PILOT_BYPASS=1` | Pass every Read through (Read hook only) |
+| `TOKEN_PILOT_DENY_THRESHOLD=<n>` | Override `hooks.denyThreshold` (default 300) |
+| `TOKEN_PILOT_ADAPTIVE_THRESHOLD=true` | Enable adaptive curve as session burns |
+| `TOKEN_PILOT_DEBUG=1` | Verbose hook logging to stderr |
+| `TOKEN_PILOT_NO_AGENT_REMINDER=1` | Suppress the "tp-* not installed" stderr nudge |
+| `TOKEN_PILOT_SUBAGENT=1` | Mark the MCP server as running inside a subagent |
+
+## Analytics & Audit
+
+```bash
+token-pilot stats                          # totals + top files from hook-events.jsonl
+token-pilot stats --session[=<id>]         # filter by session
+token-pilot stats --by-agent              # grouped by agent
+token-pilot tool-audit                    # per-tool savings distribution (cumulative)
+token-pilot tool-audit --json             # machine-readable output
+```
+
+Hook events accumulate in `.token-pilot/hook-events.jsonl`. The `session_analytics` MCP tool provides per-tool breakdown within the current session.

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.29.0",
-  "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": {