token-pilot 0.7.6 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to Token Pilot will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-03-07
+
+### Added
+- **`code_audit` tool** — find code quality issues in one call: TODO/FIXME comments (`check="todo"`), deprecated symbols (`check="deprecated"`), structural code patterns via ast-grep (`check="pattern"`), decorator search (`check="annotations"`), or combined audit (`check="all"`).
+- **Incremental index update on file changes** — file watcher now triggers `ast-index update` (debounced 2s) after edits. Keeps index fresh for find_usages, find_unused, code_audit.
+- **ast-index client methods** — `agrep()`, `todo()`, `deprecated()`, `annotations()`, `incrementalUpdate()`.
+
+### Fixed
+- **smart_read on directories** — now returns helpful message instead of EISDIR crash.
+- **MCP instructions** — added "COMBINE BOTH" section for audit tasks (Token Pilot + Grep).
+
 ## [0.7.6] - 2026-03-07
 
 ### Added

package/README.md

@@ -25,6 +25,8 @@ One command creates `.mcp.json` with token-pilot + context-mode:
 npx -y token-pilot init
 ```
 
+Safe to run in any project — if `.mcp.json` already exists, only adds missing servers without overwriting existing config.
+
 This generates:
 
 ```json
@@ -53,7 +55,7 @@ Add to your `.mcp.json` (project-level or `~/.mcp.json` for global):
 }
 ```
 
-Works with: **Cursor**, **Cline**, **Continue**, **Codex**, **Antigravity**, and any MCP-compatible client.
+Works with: **Claude Code**, **Cursor**, **Codex**, **Antigravity**, **Cline**, and any MCP-compatible client.
 
 #### Cursor
 
@@ -143,7 +145,7 @@ For more control, you can add rules to your project:
 - **Cursor** → `.cursorrules` in project root
 - **Codex** → `AGENTS.md` in project root
 
-## MCP Tools (12)
+## MCP Tools (13)
 
 ### Core Reading
 
@@ -165,6 +167,7 @@ For more control, you can add rules to your project:
 | `related_files` | manual explore | Import graph: what a file imports, what imports it, test files. |
 | `outline` | multiple `smart_read` | Compact overview of all code files in a directory. One call instead of 5-6. |
 | `find_unused` | manual | Detect dead code — unused functions, classes, variables. |
+| `code_audit` | multiple `Grep` | Code quality issues in one call: TODO/FIXME comments, deprecated symbols, structural code patterns (via ast-grep), decorator search. |
 
 ### Analytics
 
@@ -177,6 +180,7 @@ For more control, you can add rules to your project:
 ```bash
 token-pilot                      # Start MCP server (uses cwd as project root)
 token-pilot /path/to/project     # Start with specific project root
+token-pilot init [dir]           # Create/update .mcp.json (token-pilot + context-mode)
 token-pilot install-ast-index    # Download ast-index binary (auto on first run)
 token-pilot install-hook [root]  # Install PreToolUse hook
 token-pilot uninstall-hook       # Remove hook
@@ -193,7 +197,7 @@ Create `.token-pilot.json` in your project root to customize behavior:
 ```json
 {
   "smartRead": {
-    "smallFileThreshold": 80,
+    "smallFileThreshold": 200,
     "advisoryReminders": true
   },
   "cache": {
@@ -251,7 +255,6 @@ When both are configured, Token Pilot automatically:
 - Detects context-mode via `.mcp.json`
 - Suggests context-mode for large non-code files
 - Shows combined architecture info in `session_analytics`
-- Provides `export_ast_index` to feed AST data into context-mode's BM25 index
 
 **Combined savings: 60-80%** in a typical coding session.
 
@@ -339,6 +342,7 @@ src/
     related-files.ts    — related_files handler (import graph)
     outline.ts          — outline handler (directory overview)
     find-unused.ts      — find_unused handler
+    code-audit.ts       — code_audit handler (TODOs, deprecated, patterns)
     project-overview.ts — project_overview (via ast-index map + conventions)
     non-code.ts         — JSON/YAML/MD/TOML structural summaries
     export-ast-index.ts — AST export for context-mode BM25

package/dist/ast-index/client.d.ts

@@ -1,5 +1,5 @@
 import type { FileStructure } from '../types.js';
-import type { AstIndexSymbolDetail, AstIndexSearchResult, AstIndexUsageResult, AstIndexImplementation, AstIndexHierarchyNode, AstIndexRefsResponse, AstIndexMapResponse, AstIndexConventionsResponse, AstIndexCallerEntry, AstIndexCallTreeNode, AstIndexChangedEntry, AstIndexUnusedSymbol, AstIndexImportEntry } from './types.js';
+import type { AstIndexSymbolDetail, AstIndexSearchResult, AstIndexUsageResult, AstIndexImplementation, AstIndexHierarchyNode, AstIndexRefsResponse, AstIndexMapResponse, AstIndexConventionsResponse, AstIndexCallerEntry, AstIndexCallTreeNode, AstIndexChangedEntry, AstIndexUnusedSymbol, AstIndexImportEntry, AstIndexAgrepMatch, AstIndexTodoEntry, AstIndexDeprecatedEntry, AstIndexAnnotationEntry } from './types.js';
 export declare class AstIndexClient {
     private static readonly MAX_INDEX_FILES;
     private binaryPath;
@@ -11,6 +11,7 @@ export declare class AstIndexClient {
     private timeout;
     private configBinaryPath;
     private autoInstall;
+    private astGrepAvailable;
     constructor(projectRoot: string, timeout?: number, options?: {
         binaryPath?: string | null;
         autoInstall?: boolean;
@@ -92,6 +93,25 @@ export declare class AstIndexClient {
      */
     fileImports(filePath: string): Promise<AstIndexImportEntry[]>;
     private parseImportsText;
+    /** Check if ast-grep (sg) is available for structural pattern search */
+    private checkAstGrep;
+    /** Structural pattern search via ast-grep. Requires ast-grep (sg) installed. */
+    agrep(pattern: string, options?: {
+        lang?: string;
+        limit?: number;
+    }): Promise<AstIndexAgrepMatch[]>;
+    private parseAgrepText;
+    /** Find TODO/FIXME/HACK comments in the project */
+    todo(): Promise<AstIndexTodoEntry[]>;
+    private parseTodoText;
+    /** Find @Deprecated symbols in the project */
+    deprecated(): Promise<AstIndexDeprecatedEntry[]>;
+    private parseDeprecatedText;
+    /** Find symbols with a specific annotation/decorator */
+    annotations(name: string): Promise<AstIndexAnnotationEntry[]>;
+    private parseAnnotationsText;
+    /** Trigger incremental index update (called by file watcher after edits) */
+    incrementalUpdate(): Promise<void>;
     isAvailable(): boolean;
     /** Returns true if the index was built but found >50k files (node_modules leak) */
     isOversized(): boolean;

package/dist/ast-index/client.js

@@ -16,6 +16,7 @@ export class AstIndexClient {
     timeout;
     configBinaryPath;
     autoInstall;
+    astGrepAvailable = null;
     constructor(projectRoot, timeout = 5000, options) {
         this.projectRoot = projectRoot;
         this.timeout = timeout;
@@ -636,6 +637,172 @@ export class AstIndexClient {
         }
         return entries;
     }
+    // --- Code audit commands ---
+    /** Check if ast-grep (sg) is available for structural pattern search */
+    async checkAstGrep() {
+        if (this.astGrepAvailable !== null)
+            return this.astGrepAvailable;
+        try {
+            await execFileAsync('sg', ['--version'], { timeout: 3000 });
+            this.astGrepAvailable = true;
+        }
+        catch {
+            this.astGrepAvailable = false;
+        }
+        return this.astGrepAvailable;
+    }
+    /** Structural pattern search via ast-grep. Requires ast-grep (sg) installed. */
+    async agrep(pattern, options) {
+        if (this.indexDisabled || this.indexOversized)
+            return [];
+        await this.ensureIndex();
+        const available = await this.checkAstGrep();
+        if (!available) {
+            throw new Error('ast-grep (sg) not installed — required for structural pattern search.\n' +
+                'Install: brew install ast-grep  OR  npm i -g @ast-grep/cli\n' +
+                'Alternative: use Grep/ripgrep for text-based pattern search.');
+        }
+        const limit = options?.limit ?? 50;
+        const args = ['agrep', pattern];
+        if (options?.lang)
+            args.push('--lang', options.lang);
+        args.push('--limit', String(limit));
+        try {
+            const result = await this.exec(args, 15000);
+            return this.parseAgrepText(result).slice(0, limit);
+        }
+        catch (err) {
+            console.error(`[token-pilot] ast-index agrep failed: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    parseAgrepText(text) {
+        const results = [];
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            // Format: file:line:matched_text  OR  file:line: matched_text
+            const match = line.match(/^(.+?):(\d+):(.*)$/);
+            if (match) {
+                results.push({
+                    file: match[1],
+                    line: parseInt(match[2], 10),
+                    text: match[3].trim(),
+                });
+            }
+        }
+        return results;
+    }
+    /** Find TODO/FIXME/HACK comments in the project */
+    async todo() {
+        if (this.indexDisabled || this.indexOversized)
+            return [];
+        await this.ensureIndex();
+        try {
+            const result = await this.exec(['todo'], 15000);
+            return this.parseTodoText(result);
+        }
+        catch (err) {
+            console.error(`[token-pilot] ast-index todo failed: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    parseTodoText(text) {
+        const results = [];
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            // Try format: file:line: KIND: message  OR  file:line: KIND message
+            const match = line.match(/^(.+?):(\d+):\s*(TODO|FIXME|HACK|XXX|NOTE|WARN(?:ING)?)[:\s]+(.*)$/i);
+            if (match) {
+                results.push({
+                    file: match[1],
+                    line: parseInt(match[2], 10),
+                    kind: match[3].toUpperCase(),
+                    text: match[4].trim(),
+                });
+            }
+        }
+        return results;
+    }
+    /** Find @Deprecated symbols in the project */
+    async deprecated() {
+        if (this.indexDisabled || this.indexOversized)
+            return [];
+        await this.ensureIndex();
+        try {
+            const result = await this.exec(['deprecated'], 15000);
+            return this.parseDeprecatedText(result);
+        }
+        catch (err) {
+            console.error(`[token-pilot] ast-index deprecated failed: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    parseDeprecatedText(text) {
+        const results = [];
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            // Try format: kind name (file:line) - message  OR  kind name (file:line)
+            const match = line.match(/^(\w+)\s+(\S+)\s+\((.+?):(\d+)\)(?:\s*-\s*(.+))?$/);
+            if (match) {
+                results.push({
+                    kind: match[1],
+                    name: match[2],
+                    file: match[3],
+                    line: parseInt(match[4], 10),
+                    message: match[5]?.trim(),
+                });
+            }
+        }
+        return results;
+    }
+    /** Find symbols with a specific annotation/decorator */
+    async annotations(name) {
+        if (this.indexDisabled || this.indexOversized)
+            return [];
+        await this.ensureIndex();
+        try {
+            const result = await this.exec(['annotations', name], 15000);
+            return this.parseAnnotationsText(result, name);
+        }
+        catch (err) {
+            console.error(`[token-pilot] ast-index annotations failed: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
+    }
+    parseAnnotationsText(text, annotationName) {
+        const results = [];
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            // Try format: kind name (file:line)  OR  @Annotation kind name (file:line)
+            const match = line.match(/^(?:@\S+\s+)?(\w+)\s+(\S+)\s+\((.+?):(\d+)\)$/);
+            if (match) {
+                results.push({
+                    kind: match[1],
+                    name: match[2],
+                    file: match[3],
+                    line: parseInt(match[4], 10),
+                    annotation: annotationName,
+                });
+            }
+        }
+        return results;
+    }
+    /** Trigger incremental index update (called by file watcher after edits) */
+    async incrementalUpdate() {
+        if (!this.indexed || this.indexDisabled || this.indexOversized)
+            return;
+        try {
+            await this.exec(['update'], 15000);
+        }
+        catch (err) {
+            console.error(`[token-pilot] ast-index incremental update failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // --- Utility methods ---
     isAvailable() {
         return this.binaryPath !== null;
     }

package/dist/ast-index/types.d.ts

@@ -153,4 +153,33 @@ export interface AstIndexImportEntry {
     isDefault?: boolean;
     isNamespace?: boolean;
 }
+/** ast-index agrep — structural pattern search via ast-grep */
+export interface AstIndexAgrepMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+/** ast-index todo — TODO/FIXME/HACK comments */
+export interface AstIndexTodoEntry {
+    file: string;
+    line: number;
+    kind: string;
+    text: string;
+}
+/** ast-index deprecated — @Deprecated symbols */
+export interface AstIndexDeprecatedEntry {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    message?: string;
+}
+/** ast-index annotations — symbols with specific decorator/annotation */
+export interface AstIndexAnnotationEntry {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    annotation: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/core/validation.d.ts

@@ -76,6 +76,14 @@ export declare function validateFindUnusedArgs(args: unknown): {
     export_only?: boolean;
     limit?: number;
 };
+export interface CodeAuditArgs {
+    check: 'pattern' | 'todo' | 'deprecated' | 'annotations' | 'all';
+    pattern?: string;
+    name?: string;
+    lang?: string;
+    limit?: number;
+}
+export declare function validateCodeAuditArgs(args: unknown): CodeAuditArgs;
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export declare function isDangerousRoot(root: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.js

@@ -207,6 +207,33 @@ export function validateFindUnusedArgs(args) {
         limit: optionalNumber(a.limit, 'limit'),
     };
 }
+export function validateCodeAuditArgs(args) {
+    if (!args || typeof args !== 'object') {
+        throw new Error('Arguments must be an object with a "check" parameter.');
+    }
+    const a = args;
+    const validChecks = ['pattern', 'todo', 'deprecated', 'annotations', 'all'];
+    if (typeof a.check !== 'string' || !validChecks.includes(a.check)) {
+        throw new Error(`Required parameter "check" must be one of: ${validChecks.join(', ')}`);
+    }
+    if (a.check === 'pattern') {
+        if (typeof a.pattern !== 'string' || a.pattern.length === 0) {
+            throw new Error('Parameter "pattern" is required when check="pattern". Example: "except:" or "print($$$ARGS)"');
+        }
+    }
+    if (a.check === 'annotations') {
+        if (typeof a.name !== 'string' || a.name.length === 0) {
+            throw new Error('Parameter "name" is required when check="annotations". Example: "Deprecated" or "Controller"');
+        }
+    }
+    return {
+        check: a.check,
+        pattern: optionalString(a.pattern, 'pattern'),
+        name: optionalString(a.name, 'name'),
+        lang: optionalString(a.lang, 'lang'),
+        limit: optionalNumber(a.limit, 'limit'),
+    };
+}
 /** Detect roots that would cause ast-index to scan the entire filesystem */
 export function isDangerousRoot(root) {
     const normalized = root.replace(/\/+$/, '') || '/';

package/dist/git/file-watcher.d.ts

@@ -1,18 +1,27 @@
 import type { FileCache } from '../core/file-cache.js';
 import type { ContextRegistry } from '../core/context-registry.js';
+import type { AstIndexClient } from '../ast-index/client.js';
 /**
  * Watches individual files for changes and auto-invalidates cache.
  * Only watches files that have been explicitly added (via watchFile()),
  * NOT the entire project root — avoids scanning thousands of files
  * and permission errors on Docker volumes, restricted dirs, etc.
+ *
+ * Also triggers debounced ast-index incremental update on file changes
+ * to keep the index fresh for find_usages, find_unused, code_audit.
  */
 export declare class FileWatcher {
+    private static readonly UPDATE_DEBOUNCE_MS;
     private fileCache;
     private contextRegistry;
+    private astIndex;
     private watcher;
     private watchedFiles;
-    constructor(_projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry, _ignore: string[]);
+    private updateTimer;
+    constructor(_projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry, _ignore: string[], astIndex?: AstIndexClient);
     start(): void;
+    /** Debounced ast-index incremental update after file changes */
+    private scheduleIndexUpdate;
     /** Add a specific file to watch. Called after smart_read/read_symbol loads a file. */
     watchFile(filePath: string): void;
     stop(): void;

package/dist/git/file-watcher.js

@@ -5,15 +5,22 @@ import { resolve } from 'node:path';
  * Only watches files that have been explicitly added (via watchFile()),
  * NOT the entire project root — avoids scanning thousands of files
  * and permission errors on Docker volumes, restricted dirs, etc.
+ *
+ * Also triggers debounced ast-index incremental update on file changes
+ * to keep the index fresh for find_usages, find_unused, code_audit.
  */
 export class FileWatcher {
+    static UPDATE_DEBOUNCE_MS = 2000;
     fileCache;
     contextRegistry;
+    astIndex;
     watcher = null;
     watchedFiles = new Set();
-    constructor(_projectRoot, fileCache, contextRegistry, _ignore) {
+    updateTimer = null;
+    constructor(_projectRoot, fileCache, contextRegistry, _ignore, astIndex) {
         this.fileCache = fileCache;
         this.contextRegistry = contextRegistry;
+        this.astIndex = astIndex ?? null;
     }
     start() {
         // Start with an empty watcher — files are added on demand via watchFile()
@@ -30,14 +37,26 @@ export class FileWatcher {
             if (this.fileCache.get(absPath)) {
                 this.fileCache.invalidate(absPath);
             }
+            this.scheduleIndexUpdate();
         });
         this.watcher.on('unlink', (filePath) => {
             const absPath = resolve(filePath);
             this.fileCache.invalidate(absPath);
             this.contextRegistry.forget(absPath);
             this.watchedFiles.delete(absPath);
+            this.scheduleIndexUpdate();
         });
     }
+    /** Debounced ast-index incremental update after file changes */
+    scheduleIndexUpdate() {
+        if (!this.astIndex)
+            return;
+        if (this.updateTimer)
+            clearTimeout(this.updateTimer);
+        this.updateTimer = setTimeout(() => {
+            this.astIndex?.incrementalUpdate().catch(() => { });
+        }, FileWatcher.UPDATE_DEBOUNCE_MS);
+    }
     /** Add a specific file to watch. Called after smart_read/read_symbol loads a file. */
     watchFile(filePath) {
         const absPath = resolve(filePath);
@@ -49,6 +68,9 @@ export class FileWatcher {
         this.watchedFiles.add(absPath);
     }
     stop() {
+        if (this.updateTimer)
+            clearTimeout(this.updateTimer);
+        this.updateTimer = null;
         this.watcher?.close();
         this.watcher = null;
         this.watchedFiles.clear();

package/dist/handlers/code-audit.d.ts

@@ -0,0 +1,9 @@
+import type { AstIndexClient } from '../ast-index/client.js';
+import type { CodeAuditArgs } from '../core/validation.js';
+export declare function handleCodeAudit(args: CodeAuditArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=code-audit.d.ts.map

package/dist/handlers/code-audit.js

@@ -0,0 +1,200 @@
+import { relative } from 'node:path';
+export async function handleCodeAudit(args, projectRoot, astIndex) {
+    if (astIndex.isDisabled() || astIndex.isOversized()) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'ast-index is not available (project root too broad or index oversized). Use Grep/ripgrep for pattern search.',
+                }],
+        };
+    }
+    const limit = args.limit ?? 50;
+    switch (args.check) {
+        case 'pattern':
+            return handlePattern(args.pattern, args.lang, limit, projectRoot, astIndex);
+        case 'todo':
+            return handleTodo(limit, projectRoot, astIndex);
+        case 'deprecated':
+            return handleDeprecated(limit, projectRoot, astIndex);
+        case 'annotations':
+            return handleAnnotations(args.name, limit, projectRoot, astIndex);
+        case 'all':
+            return handleAll(limit, projectRoot, astIndex);
+        default:
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Unknown check type: "${args.check}". Use: pattern, todo, deprecated, annotations, all`,
+                    }],
+            };
+    }
+}
+function rel(projectRoot, absPath) {
+    return relative(projectRoot, absPath) || absPath;
+}
+async function handlePattern(pattern, lang, limit, projectRoot, astIndex) {
+    try {
+        const matches = await astIndex.agrep(pattern, { lang, limit });
+        if (matches.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `PATTERN SEARCH: "${pattern}"${lang ? ` (${lang})` : ''}\n\nNo matches found.\n\nHINT: Try Grep/ripgrep for text-based search if the pattern is not structural.`,
+                    }],
+            };
+        }
+        // Group by file
+        const byFile = new Map();
+        for (const m of matches) {
+            const key = rel(projectRoot, m.file);
+            if (!byFile.has(key))
+                byFile.set(key, []);
+            byFile.get(key).push({ line: m.line, text: m.text });
+        }
+        const lines = [
+            `PATTERN SEARCH: "${pattern}"${lang ? ` (${lang})` : ''} — ${matches.length} matches in ${byFile.size} files`,
+            '',
+        ];
+        for (const [file, items] of byFile) {
+            lines.push(`${file}:`);
+            for (const item of items) {
+                lines.push(`  L${item.line}: ${item.text}`);
+            }
+            lines.push('');
+        }
+        lines.push('HINT: Use read_symbol() to inspect specific matches, or Grep for text-based counting.');
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (err) {
+        // ast-grep not installed — return the error message
+        return {
+            content: [{
+                    type: 'text',
+                    text: `PATTERN SEARCH ERROR:\n${err instanceof Error ? err.message : String(err)}\n\nFallback: Use Grep/ripgrep for text-based pattern search.`,
+                }],
+        };
+    }
+}
+async function handleTodo(limit, projectRoot, astIndex) {
+    const entries = await astIndex.todo();
+    const limited = entries.slice(0, limit);
+    if (limited.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'TODO/FIXME COMMENTS: none found.\n\nHINT: ast-index may not detect all comment formats. Try Grep: grep -rn "TODO\\|FIXME\\|HACK" --include="*.ts"',
+                }],
+        };
+    }
+    // Group by kind
+    const byKind = new Map();
+    for (const e of limited) {
+        const kind = e.kind;
+        if (!byKind.has(kind))
+            byKind.set(kind, []);
+        byKind.get(kind).push({ file: rel(projectRoot, e.file), line: e.line, text: e.text });
+    }
+    const lines = [
+        `TODO/FIXME COMMENTS: ${limited.length} found${entries.length > limit ? ` (showing ${limit} of ${entries.length})` : ''}`,
+        '',
+    ];
+    for (const [kind, items] of byKind) {
+        lines.push(`${kind} (${items.length}):`);
+        for (const item of items) {
+            lines.push(`  ${item.file}:${item.line} — ${item.text}`);
+        }
+        lines.push('');
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+async function handleDeprecated(limit, projectRoot, astIndex) {
+    const entries = await astIndex.deprecated();
+    const limited = entries.slice(0, limit);
+    if (limited.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'DEPRECATED SYMBOLS: none found.\n\nHINT: ast-index detects @Deprecated annotations. Try Grep for other deprecation patterns.',
+                }],
+        };
+    }
+    const lines = [
+        `DEPRECATED SYMBOLS: ${limited.length} found${entries.length > limit ? ` (showing ${limit} of ${entries.length})` : ''}`,
+        '',
+    ];
+    for (const e of limited) {
+        const loc = `${rel(projectRoot, e.file)}:${e.line}`;
+        lines.push(`  ${e.kind} ${e.name}  ${loc}${e.message ? ` — ${e.message}` : ''}`);
+    }
+    lines.push('');
+    lines.push('HINT: Use read_symbol() to inspect deprecated symbols before removing them.');
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+async function handleAnnotations(name, limit, projectRoot, astIndex) {
+    const entries = await astIndex.annotations(name);
+    const limited = entries.slice(0, limit);
+    if (limited.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `ANNOTATIONS @${name}: none found.\n\nHINT: Try Grep for text-based search: grep -rn "@${name}" --include="*.ts"`,
+                }],
+        };
+    }
+    // Group by file
+    const byFile = new Map();
+    for (const e of limited) {
+        const key = rel(projectRoot, e.file);
+        if (!byFile.has(key))
+            byFile.set(key, []);
+        byFile.get(key).push({ name: e.name, kind: e.kind, line: e.line });
+    }
+    const lines = [
+        `ANNOTATIONS @${name}: ${limited.length} found in ${byFile.size} files${entries.length > limit ? ` (showing ${limit} of ${entries.length})` : ''}`,
+        '',
+    ];
+    for (const [file, items] of byFile) {
+        lines.push(`${file}:`);
+        for (const item of items) {
+            lines.push(`  L${item.line}: ${item.kind} ${item.name}`);
+        }
+        lines.push('');
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+async function handleAll(limit, projectRoot, astIndex) {
+    // Run todo + deprecated in parallel
+    const [todos, deprecated] = await Promise.all([
+        astIndex.todo(),
+        astIndex.deprecated(),
+    ]);
+    const sections = ['CODE AUDIT SUMMARY', ''];
+    // TODOs
+    const todoLimited = todos.slice(0, limit);
+    if (todoLimited.length === 0) {
+        sections.push('TODO/FIXME: none found');
+    }
+    else {
+        sections.push(`TODO/FIXME: ${todoLimited.length} comments${todos.length > limit ? ` (${todos.length} total)` : ''}`);
+        for (const e of todoLimited) {
+            sections.push(`  ${rel(projectRoot, e.file)}:${e.line} [${e.kind}] ${e.text}`);
+        }
+    }
+    sections.push('');
+    // Deprecated
+    const depLimited = deprecated.slice(0, limit);
+    if (depLimited.length === 0) {
+        sections.push('DEPRECATED: none found');
+    }
+    else {
+        sections.push(`DEPRECATED: ${depLimited.length} symbols${deprecated.length > limit ? ` (${deprecated.length} total)` : ''}`);
+        for (const e of depLimited) {
+            sections.push(`  ${rel(projectRoot, e.file)}:${e.line} ${e.kind} ${e.name}${e.message ? ` — ${e.message}` : ''}`);
+        }
+    }
+    sections.push('');
+    sections.push('HINT: Use code_audit(check="pattern", pattern="...") for structural pattern search (requires ast-grep).');
+    sections.push('      Use Grep for text-based counting and regex search.');
+    return { content: [{ type: 'text', text: sections.join('\n') }] };
+}
+//# sourceMappingURL=code-audit.js.map

package/dist/handlers/smart-read.js

@@ -6,6 +6,16 @@ import { resolveSafePath } from '../core/validation.js';
 import { isNonCodeStructured, handleNonCodeRead } from './non-code.js';
 export async function handleSmartRead(args, projectRoot, astIndex, fileCache, contextRegistry, config) {
     const absPath = resolveSafePath(projectRoot, args.path);
+    // 0. Guard: directory passed instead of file
+    const fileStat0 = await stat(absPath).catch(() => null);
+    if (fileStat0?.isDirectory()) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `"${args.path}" is a directory. Use outline("${args.path}") for directory overview, or smart_read a specific file inside it.`,
+                }],
+        };
+    }
     // 1. Read file content
     const content = await readFile(absPath, 'utf-8');
     const lines = content.split('\n');

package/dist/server.js

@@ -26,9 +26,10 @@ import { handleFindUnused } from './handlers/find-unused.js';
 import { handleReadForEdit } from './handlers/read-for-edit.js';
 import { handleRelatedFiles } from './handlers/related-files.js';
 import { handleOutline } from './handlers/outline.js';
+import { handleCodeAudit } from './handlers/code-audit.js';
 import { detectContextMode } from './integration/context-mode-detector.js';
 import { estimateTokens } from './core/token-estimator.js';
-import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, } from './core/validation.js';
+import { resolveSafePath, validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -152,7 +153,7 @@ export async function createServer(projectRoot, options) {
     // Watches only files that have been loaded — NOT the entire project root
     let fileWatcher = null;
     if (config.cache.watchFiles) {
-        fileWatcher = new FileWatcher(projectRoot, fileCache, contextRegistry, config.ignore);
+        fileWatcher = new FileWatcher(projectRoot, fileCache, contextRegistry, config.ignore, astIndex);
         fileWatcher.start();
         fileCache.onSet((filePath) => fileWatcher?.watchFile(filePath));
     }
@@ -180,13 +181,22 @@ export async function createServer(projectRoot, options) {
             '• New codebase → project_overview first',
             '• Reading file again → smart_read (returns compact reminder, not full content)',
             '• Multiple files → smart_read_many (batch, max 20)',
+            '• Code quality audit → code_audit (TODOs, deprecated, structural code patterns)',
             '',
             'WHEN TO USE DEFAULT TOOLS (Token Pilot adds no value):',
             '• Small files (≤200 lines) → smart_read returns full content anyway, same as Read',
-            '• Regex/pattern search (e.g. TODO.*fix) → use Grep/ripgrep, NOT find_usages',
+            '• Regex text search (e.g. TODO.*fix) → use Grep/ripgrep',
+            '• Counting occurrences (e.g. how many `any` types?) → use Grep count mode',
+            '• Finding code duplication → use Grep to search for repeated patterns',
             '• Non-code files (JSON, YAML, Markdown, configs) → smart_read handles these but default Read works too',
             '• You need exact raw content for copy-paste → use Read',
             '',
+            'COMBINE BOTH for audits and code review:',
+            '• Structure/navigation → Token Pilot (project_overview, outline, smart_read)',
+            '• Code issues → code_audit (TODOs, deprecated, structural patterns like bare except:)',
+            '• Text pattern search/counting → Grep (regex, count mode)',
+            '• Deep dive into specific code → read_symbol (after finding issues)',
+            '',
             'WORKFLOW: project_overview → smart_read → read_symbol → read_for_edit → edit → read_diff',
         ].join('\n'),
     });
@@ -340,6 +350,25 @@ export async function createServer(projectRoot, options) {
                     },
                 },
             },
+            {
+                name: 'code_audit',
+                description: 'Find code quality issues: TODO/FIXME comments, deprecated symbols, structural code patterns (bare except:, print() calls). Use for project-wide audits.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        check: {
+                            type: 'string',
+                            enum: ['pattern', 'todo', 'deprecated', 'annotations', 'all'],
+                            description: '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), "all" (todo + deprecated summary)',
+                        },
+                        pattern: { type: 'string', description: 'Code pattern for check="pattern". ast-grep syntax: "except:" finds bare excepts, "print($$$ARGS)" finds print calls.' },
+                        name: { type: 'string', description: 'Decorator/annotation name for check="annotations". Example: "Deprecated", "Controller"' },
+                        lang: { type: 'string', description: 'Language filter for check="pattern" (e.g., "python", "typescript")' },
+                        limit: { type: 'number', description: 'Max results (default: 50)' },
+                    },
+                    required: ['check'],
+                },
+            },
         ],
     }));
     // Helper: get real full-file token count for honest analytics
@@ -475,6 +504,13 @@ export async function createServer(projectRoot, options) {
                     analytics.record({ tool: 'find_unused', path: unusedArgs.module ?? 'all', tokensReturned: estimateTokens(unusedText), tokensWouldBe: estimateTokens(unusedText), timestamp: Date.now() });
                     return unusedResult;
                 }
+                case 'code_audit': {
+                    const auditArgs = validateCodeAuditArgs(args);
+                    const auditResult = await handleCodeAudit(auditArgs, projectRoot, astIndex);
+                    const auditText = auditResult.content[0]?.text ?? '';
+                    analytics.record({ tool: 'code_audit', path: auditArgs.check, tokensReturned: estimateTokens(auditText), tokensWouldBe: estimateTokens(auditText), timestamp: Date.now() });
+                    return auditResult;
+                }
                 default:
                     return {
                         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "MCP server that reduces token consumption in AI coding assistants via AST-aware lazy file reading",
   "type": "module",
   "main": "dist/index.js",