grepmax 0.7.33 → 0.7.35

package/dist/commands/mcp.js

@@ -84,260 +84,110 @@ const watcher_registry_1 = require("../lib/utils/watcher-registry");
 const TOOLS = [
     {
         name: "semantic_search",
-        description: "Search code by meaning within a directory. Use natural language queries like 'where do we validate permissions'. Searches the current project by default. Use `root` to search a different directory's index (e.g. a parent directory).",
+        description: "Search code by meaning. Use scope:'all' for cross-project. Prefer CLI: gmax \"query\" --plain",
         inputSchema: {
             type: "object",
             properties: {
-                query: {
-                    type: "string",
-                    description: "Natural language search query. Be specific — more words give better results.",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max results to return (default 3, max 50)",
-                },
-                root: {
-                    type: "string",
-                    description: "Directory to search (absolute or relative path). Defaults to the current project root. Use to search a parent or sibling directory's indexed code.",
-                },
-                path: {
-                    type: "string",
-                    description: "Restrict search to files under this path prefix (e.g. 'src/auth/'). Relative to the search root.",
-                },
-                detail: {
-                    type: "string",
-                    description: "Output detail: 'pointer' (default, metadata only), 'code' (4-line snippets), or 'full' (complete chunk content with line numbers)",
-                },
-                min_score: {
-                    type: "number",
-                    description: "Minimum relevance score (0-1). Results below this threshold are filtered out. Default: 0 (no filtering)",
-                },
-                max_per_file: {
-                    type: "number",
-                    description: "Max results per file (default: no cap). Useful to get diversity across files.",
-                },
-                file: {
-                    type: "string",
-                    description: "Filter to files matching this name (e.g. 'syncer.ts'). Matches the filename, not the full path.",
-                },
-                exclude: {
-                    type: "string",
-                    description: "Exclude files under this path prefix (e.g. 'tests/' or 'dist/').",
-                },
-                language: {
-                    type: "string",
-                    description: "Filter by file extension (e.g. 'ts', 'py', 'go'). Omit the dot.",
-                },
-                role: {
-                    type: "string",
-                    description: "Filter by chunk role: 'ORCHESTRATION' (logic/flow), 'DEFINITION' (types/classes), or 'IMPLEMENTATION'.",
-                },
-                context_lines: {
-                    type: "number",
-                    description: "Include N lines before and after the chunk (like grep -C). Only with detail 'code' or 'full'. Max 20.",
-                },
-                mode: {
-                    type: "string",
-                    description: "Search mode: 'default' (semantic only) or 'symbol' (semantic + call graph trace appended). Use 'symbol' when query is a function/class name.",
-                },
-                include_imports: {
-                    type: "boolean",
-                    description: "Prepend the file's import/require statements to each result. Deduped per file.",
-                },
-                name_pattern: {
-                    type: "string",
-                    description: "Regex to filter by symbol name (e.g. 'handle.*Auth'). Case-insensitive. Applied after search.",
-                },
-            },
-            required: ["query"],
-        },
-    },
-    {
-        name: "search_all",
-        description: "Search ALL indexed code across every directory. Use when you need to find code that could be anywhere. Returns results with full absolute paths so you know which project each result is from.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                query: {
-                    type: "string",
-                    description: "Natural language search query.",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max results to return (default 3, max 50)",
-                },
-                detail: {
-                    type: "string",
-                    description: "Output detail: 'pointer' (default), 'code' (snippets), or 'full' (complete content)",
-                },
-                min_score: {
-                    type: "number",
-                    description: "Minimum relevance score (0-1). Default: 0",
-                },
-                max_per_file: {
-                    type: "number",
-                    description: "Max results per file (default: no cap).",
-                },
-                file: {
-                    type: "string",
-                    description: "Filter to files matching this name (e.g. 'syncer.ts').",
-                },
-                exclude: {
-                    type: "string",
-                    description: "Exclude files under this path prefix (e.g. 'tests/').",
-                },
-                language: {
-                    type: "string",
-                    description: "Filter by file extension (e.g. 'ts', 'py').",
-                },
-                role: {
-                    type: "string",
-                    description: "Filter by role: 'ORCHESTRATION', 'DEFINITION', or 'IMPLEMENTATION'.",
-                },
-                projects: {
-                    type: "string",
-                    description: "Comma-separated project names to include (e.g. 'platform,osgrep'). Use index_status to see names.",
-                },
-                exclude_projects: {
-                    type: "string",
-                    description: "Comma-separated project names to exclude (e.g. 'capstone,power').",
-                },
-                context_lines: {
-                    type: "number",
-                    description: "Include N lines before/after chunk. Only with detail 'code' or 'full'. Max 20.",
-                },
-                include_imports: {
-                    type: "boolean",
-                    description: "Prepend file's import statements to each result.",
-                },
-                name_pattern: {
-                    type: "string",
-                    description: "Regex to filter by symbol name (e.g. 'handle.*Auth').",
-                },
+                query: { type: "string", description: "Natural language query (5+ words recommended)" },
+                limit: { type: "number", description: "Max results (default 3, max 50)" },
+                root: { type: "string", description: "Search a different directory (absolute path)" },
+                path: { type: "string", description: "Path prefix filter (e.g. 'src/auth/')" },
+                detail: { type: "string", description: "'pointer' (default), 'code', or 'full'" },
+                min_score: { type: "number", description: "Min score 0-1 (default 0)" },
+                max_per_file: { type: "number", description: "Max results per file" },
+                file: { type: "string", description: "Filename filter (e.g. 'syncer.ts')" },
+                exclude: { type: "string", description: "Exclude path prefix (e.g. 'tests/')" },
+                language: { type: "string", description: "Extension filter (e.g. 'ts', 'py')" },
+                role: { type: "string", description: "'ORCHESTRATION', 'DEFINITION', or 'IMPLEMENTATION'" },
+                context_lines: { type: "number", description: "Lines before/after chunk (max 20)" },
+                mode: { type: "string", description: "'default' or 'symbol' (appends call graph)" },
+                include_imports: { type: "boolean", description: "Prepend file imports to results" },
+                name_pattern: { type: "string", description: "Regex filter on symbol name" },
+                scope: { type: "string", description: "'project' (default) or 'all' (search everything)" },
+                projects: { type: "string", description: "Project names to include (comma-separated)" },
+                exclude_projects: { type: "string", description: "Project names to exclude (comma-separated)" },
             },
             required: ["query"],
         },
     },
     {
         name: "code_skeleton",
-        description: "Show the structure of source files — signatures with bodies collapsed (~4x fewer tokens). Accepts a file path, a directory path, or comma-separated file paths.",
+        description: "File structure with bodies collapsed (~4x fewer tokens). Accepts file, directory, or comma-separated paths.",
         inputSchema: {
             type: "object",
             properties: {
-                target: {
-                    type: "string",
-                    description: "File path, directory path (e.g. 'src/lib/search/'), or comma-separated files (e.g. 'src/a.ts,src/b.ts'). Relative to project root.",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max files for directory mode (default 10, max 20). Ignored for single files.",
-                },
-                format: {
-                    type: "string",
-                    description: "Output format: 'text' (default) or 'json' (structured symbol list with names, lines, signatures).",
-                },
+                target: { type: "string", description: "File, directory, or comma-separated paths" },
+                limit: { type: "number", description: "Max files for directory mode (default 10)" },
+                format: { type: "string", description: "'text' (default) or 'json'" },
             },
             required: ["target"],
         },
     },
     {
         name: "trace_calls",
-        description: "Trace the call graph for a symbol — who calls it (callers) and what it calls (callees). Searches across ALL indexed code to follow calls across project boundaries.",
+        description: "Call graph: importers, callers (multi-hop), callees with file:line.",
         inputSchema: {
             type: "object",
             properties: {
-                symbol: {
-                    type: "string",
-                    description: "The function, method, or class name to trace (e.g. 'handleAuth')",
-                },
-                depth: {
-                    type: "number",
-                    description: "Traversal depth for callers (default 1, max 3). depth: 2 shows callers-of-callers.",
-                },
+                symbol: { type: "string", description: "Function/class name to trace" },
+                depth: { type: "number", description: "Caller depth (default 1, max 3)" },
             },
             required: ["symbol"],
         },
     },
     {
         name: "list_symbols",
-        description: "List indexed symbols (functions, classes, types) with their definition locations. Useful for finding where things are defined without knowing exact names.",
+        description: "List indexed symbols with role and export status.",
         inputSchema: {
             type: "object",
             properties: {
-                pattern: {
-                    type: "string",
-                    description: "Filter symbols by name (case-insensitive substring match)",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max symbols to return (default 20, max 100)",
-                },
-                path: {
-                    type: "string",
-                    description: "Only include symbols defined under this path prefix",
-                },
+                pattern: { type: "string", description: "Name filter (case-insensitive)" },
+                limit: { type: "number", description: "Max results (default 20)" },
+                path: { type: "string", description: "Path prefix filter" },
             },
         },
     },
     {
         name: "index_status",
-        description: "Check the status of the gmax index. Returns indexed directories, chunk counts, embed mode, index age, and watcher status.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "Index health: chunks, files, projects, watcher status.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "summarize_directory",
-        description: "Generate LLM summaries for indexed code in a directory. Run after indexing. Summaries are stored and returned in search results. Requires the summarizer server on port 8101.",
+        description: "Generate LLM summaries for indexed chunks.",
         inputSchema: {
             type: "object",
             properties: {
-                path: {
-                    type: "string",
-                    description: "Directory to summarize (absolute or relative). Defaults to current project root.",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max chunks to summarize per call (default 200, max 5000). Run again to continue.",
-                },
+                path: { type: "string", description: "Directory to summarize (default: project root)" },
+                limit: { type: "number", description: "Max chunks (default 200, max 5000)" },
             },
         },
     },
     {
         name: "summarize_project",
-        description: "High-level overview of an indexed project — languages, directory structure, role distribution, key symbols, and entry points. Use when first exploring a codebase.",
+        description: "Project overview: languages, structure, roles, key symbols, entry points.",
         inputSchema: {
             type: "object",
             properties: {
-                root: {
-                    type: "string",
-                    description: "Project root (absolute path). Defaults to current project.",
-                },
+                root: { type: "string", description: "Project root (default: current)" },
             },
         },
     },
     {
         name: "related_files",
-        description: "Find files related to a given file by shared symbol references. Shows dependencies (what this file calls) and dependents (what calls this file).",
+        description: "Find dependencies and dependents of a file by shared symbols.",
         inputSchema: {
             type: "object",
             properties: {
-                file: {
-                    type: "string",
-                    description: "File path relative to project root (e.g. 'src/lib/index/syncer.ts')",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max related files per direction (default 10)",
-                },
+                file: { type: "string", description: "File path relative to project root" },
+                limit: { type: "number", description: "Max results per direction (default 10)" },
             },
             required: ["file"],
         },
     },
     {
         name: "recent_changes",
-        description: "Show recently modified files in the index. Useful after pulls or merges to see what changed.",
+        description: "Recently modified indexed files with timestamps.",
         inputSchema: {
             type: "object",
             properties: {
@@ -513,11 +363,12 @@ exports.mcp = new commander_1.Command("mcp")
     }
     // --- Tool handlers ---
     function handleSemanticSearch(args_1) {
-        return __awaiter(this, arguments, void 0, function* (args, searchAll = false) {
+        return __awaiter(this, arguments, void 0, function* (args, isSearchAll = false) {
             var _a;
             const query = String(args.query || "");
             if (!query)
                 return err("Missing required parameter: query");
+            const searchAll = isSearchAll || args.scope === "all";
             const limit = Math.min(Math.max(Number(args.limit) || 3, 1), 50);
             ensureWatcher();
             if (_indexing) {

package/dist/commands/search.js

@@ -345,6 +345,7 @@ exports.search = new commander_1.Command("search")
     .option("--imports", "Prepend file imports to each result", false)
     .option("--name <regex>", "Filter results by symbol name regex")
     .option("-C, --context <n>", "Include N lines before/after each result")
+    .option("--agent", "Ultra-compact output for AI agents (one line per result)", false)
     .argument("<pattern>", "Natural language query (e.g. \"where do we handle auth?\")")
     .argument("[path]", "Restrict search to this path prefix")
     .addHelpText("after", `
@@ -357,7 +358,7 @@ Examples:
   gmax "handler" --name "handle.*" --exclude tests/
 `)
     .action((pattern, exec_path, _options, cmd) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
     const options = cmd.optsWithGlobals();
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
@@ -451,8 +452,7 @@ Examples:
         process.env.GMAX_PROJECT_ROOT = projectRoot;
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         // Check for active indexing lock and warn if present
-        // This allows agents (via shim) to know results might be partial.
-        if ((0, lock_1.isLocked)(paths.dataDir)) {
+        if (!options.agent && (0, lock_1.isLocked)(paths.dataDir)) {
             console.warn("⚠️  Warning: Indexing in progress... search results may be incomplete.");
         }
         const hasRows = yield vectorDb.hasAnyRows();
@@ -506,7 +506,7 @@ Examples:
                     stdio: "ignore",
                 });
             }
-            catch (_f) {
+            catch (_p) {
                 // Watcher may already be running — ignore
             }
         }
@@ -532,7 +532,7 @@ Examples:
         if (options.role)
             searchFilters.role = options.role;
         const searchResult = yield searcher.search(pattern, parseInt(options.m, 10), { rerank: true }, Object.keys(searchFilters).length > 0 ? searchFilters : undefined, pathFilter);
-        if ((_e = searchResult.warnings) === null || _e === void 0 ? void 0 : _e.length) {
+        if (!options.agent && ((_e = searchResult.warnings) === null || _e === void 0 ? void 0 : _e.length)) {
             for (const w of searchResult.warnings) {
                 console.warn(`Warning: ${w}`);
             }
@@ -549,10 +549,65 @@ Examples:
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_g) {
+            catch (_q) {
                 // Invalid regex — skip
             }
         }
+        // Agent mode: ultra-compact one-line-per-result output
+        if (options.agent) {
+            if (!filteredData.length) {
+                console.log("(none)");
+            }
+            else {
+                for (const r of filteredData) {
+                    const absP = (_h = (_f = r.path) !== null && _f !== void 0 ? _f : (_g = r.metadata) === null || _g === void 0 ? void 0 : _g.path) !== null && _h !== void 0 ? _h : "";
+                    const relPath = absP.startsWith(effectiveRoot)
+                        ? absP.slice(effectiveRoot.length + 1)
+                        : absP;
+                    const startLine = Math.max(1, ((_m = (_k = (_j = r.startLine) !== null && _j !== void 0 ? _j : r.start_line) !== null && _k !== void 0 ? _k : (_l = r.generated_metadata) === null || _l === void 0 ? void 0 : _l.start_line) !== null && _m !== void 0 ? _m : 0) + 1);
+                    const defs = Array.isArray(r.defined_symbols)
+                        ? r.defined_symbols
+                        : [];
+                    const symbol = defs[0] || "";
+                    const role = ((_o = r.role) !== null && _o !== void 0 ? _o : "")
+                        .slice(0, 4)
+                        .toUpperCase();
+                    const summary = r.summary
+                        ? ` — ${r.summary}`
+                        : "";
+                    const sym = symbol ? ` ${symbol}` : "";
+                    const rl = role ? ` [${role}]` : "";
+                    console.log(`${relPath}:${startLine}${sym}${rl}${summary}`);
+                }
+            }
+            // Agent trace (compact)
+            if (options.symbol && vectorDb && filteredData.length > 0) {
+                try {
+                    const { GraphBuilder } = yield Promise.resolve().then(() => __importStar(require("../lib/graph/graph-builder")));
+                    const builder = new GraphBuilder(vectorDb);
+                    const graph = yield builder.buildGraphMultiHop(pattern, 1);
+                    if (graph.center) {
+                        console.log("---");
+                        for (const t of graph.callerTree) {
+                            const rel = t.node.file.startsWith(effectiveRoot)
+                                ? t.node.file.slice(effectiveRoot.length + 1)
+                                : t.node.file;
+                            console.log(`<- ${t.node.symbol} ${rel}:${t.node.line + 1}`);
+                        }
+                        for (const c of graph.callees.slice(0, 10)) {
+                            if (c.file) {
+                                const rel = c.file.startsWith(effectiveRoot)
+                                    ? c.file.slice(effectiveRoot.length + 1)
+                                    : c.file;
+                                console.log(`-> ${c.symbol} ${rel}:${c.line + 1}`);
+                            }
+                        }
+                    }
+                }
+                catch (_r) { }
+            }
+            return;
+        }
         if (options.skeleton) {
             yield outputSkeletons(filteredData, projectRoot, parseInt(options.m, 10), vectorDb);
             return;
@@ -634,7 +689,7 @@ Examples:
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_h) {
+            catch (_s) {
                 // Trace failed — skip silently
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.7.33",
+  "version": "0.7.35",
   "author": "Robert Owens <robowens@me.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.7.33",
+  "version": "0.7.35",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/hooks/start.js

@@ -89,7 +89,7 @@ async function main() {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
       additionalContext:
-        'gmax ready. PREFER CLI over MCP tools — use Bash(gmax "query" --plain) for search, Bash(gmax trace <symbol>) for call graphs, Bash(gmax skeleton <path>) for file structure. CLI is 2x more token-efficient than MCP tool calls. Always add --plain flag.',
+        'gmax ready. PREFER CLI over MCP — use Bash(gmax "query" --agent) for search (one line per result, 89% fewer tokens). Bash(gmax trace <symbol>) for call graphs. Bash(gmax skeleton <path>) for structure. Always use --agent flag.',
     },
   };
   process.stdout.write(JSON.stringify(response));

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: grepmax
 description: Semantic code search. Use alongside grep - grep for exact strings, gmax for concepts.
-allowed-tools: "mcp__grepmax__semantic_search, mcp__grepmax__search_all, mcp__grepmax__code_skeleton, mcp__grepmax__trace_calls, mcp__grepmax__list_symbols, mcp__grepmax__index_status, mcp__grepmax__summarize_directory, mcp__grepmax__summarize_project, mcp__grepmax__related_files, mcp__grepmax__recent_changes, Bash(gmax:*), Read"
+allowed-tools: "mcp__grepmax__semantic_search, mcp__grepmax__code_skeleton, mcp__grepmax__trace_calls, mcp__grepmax__list_symbols, mcp__grepmax__index_status, mcp__grepmax__summarize_directory, mcp__grepmax__summarize_project, mcp__grepmax__related_files, mcp__grepmax__recent_changes, Bash(gmax:*), Read"
 ---
 
 ## What gmax does
@@ -13,29 +13,29 @@ Semantic code search — finds code by meaning, not just strings.
 
 ## IMPORTANT: Use CLI, not MCP tools
 
-**Always prefer `Bash(gmax ...)` over MCP tool calls.** The CLI is ~2x more token-efficient because MCP tool schemas add ~800 tokens of overhead per call. The CLI has full feature parity with every MCP tool.
+**Always prefer `Bash(gmax ...)` over MCP tool calls.** Use `--agent` for the most token-efficient output (one line per result, ~89% fewer tokens than default).
 
 ```
-Bash(gmax "auth handler" --role ORCHESTRATION --lang ts --plain -m 3)
+Bash(gmax "auth handler" --role ORCHESTRATION --lang ts --agent -m 3)
 ```
 
-**Only use MCP tools** for `index_status` (quick health check) or `summarize_directory` (LLM summaries). For everything else, use CLI.
+**Only use MCP tools** for `index_status` or `summarize_directory`. For everything else, use CLI with `--agent`.
 
 ## CLI commands (use these)
 
-### Search — `gmax "query" --plain`
+### Search — `gmax "query" --agent`
 ```
-gmax "where do we handle authentication" --plain
-gmax "database connection pooling" --role ORCHESTRATION --plain -m 5
-gmax "error handling" --lang ts --exclude tests/ --plain
-gmax "VectorDB" --symbol --plain          # search + call graph in one shot
-gmax "handler" --name "handle.*" --plain   # regex filter on symbol names
-gmax "auth" --file handler.ts --plain      # filter by filename
-gmax "query" -C 5 --plain                  # include context lines
-gmax "query" --imports --plain             # show file imports
+gmax "where do we handle authentication" --agent
+gmax "database connection pooling" --role ORCHESTRATION --agent -m 5
+gmax "error handling" --lang ts --exclude tests/ --agent
+gmax "VectorDB" --symbol --agent          # search + call graph in one shot
+gmax "handler" --name "handle.*" --agent   # regex filter on symbol names
+gmax "auth" --file handler.ts --agent      # filter by filename
 ```
 
-All flags: `--plain -m <n> --per-file <n> --min-score <n> --root <dir> --file <name> --exclude <prefix> --lang <ext> --role <role> --symbol --imports --name <regex> -C <n> --compact --content --scores --skeleton`
+Output format: `file:line symbol [role] — summary` (one line per result, no headers/footers)
+
+All flags: `--agent --plain -m <n> --per-file <n> --min-score <n> --root <dir> --file <name> --exclude <prefix> --lang <ext> --role <role> --symbol --imports --name <regex> -C <n> --compact --content --scores --skeleton`
 
 ### Trace — `gmax trace <symbol>`
 ```
@@ -85,18 +85,13 @@ gmax doctor                                # health check
 6. **Context** — `Bash(gmax related <file>)` to see what else to look at
 7. **Changes** — `Bash(gmax recent)` after pulls
 
-## MCP tools (only when CLI isn't suitable)
-
-MCP tools are available but consume more tokens. Use them only for:
-- `index_status` — quick health check (no CLI equivalent that's cheaper)
-- `summarize_directory` — LLM summary generation
-- `semantic_search` with `detail: "pointer"` — when you need the structured pointer format
+## MCP tools
 
-Full MCP tool documentation: semantic_search (16 params), search_all, code_skeleton, trace_calls, list_symbols, index_status, summarize_project, related_files, recent_changes, summarize_directory.
+Use MCP only for `index_status` and `summarize_directory`. Use CLI for everything else. For cross-project search, use `scope: "all"` on semantic_search (replaces search_all).
 
 ## Tips
 
-- **Always use `--plain`** on CLI searches — agent-friendly output without ANSI codes.
+- **Always use `--agent`** on CLI searches — one line per result, most token-efficient.
 - **Be specific.** 5+ words. "auth" returns noise. "where does the server validate JWT tokens" is specific.
 - **Use `--role ORCHESTRATION`** to skip type definitions and find the actual logic.
 - **Use `--symbol`** when the query is a function/class name — gets search + trace in one call.