grepmax 0.7.22 → 0.7.24

package/README.md

@@ -100,12 +100,15 @@ In our public benchmarks, `grepmax` can save about 20% of your LLM tokens and de
 
 | Tool | Description |
 | --- | --- |
-| `semantic_search` | Code search by meaning. Returns pointers (symbol, file:line, role, calls, summary) by default. Use `root` for cross-directory search, `detail: "code"` for snippets. |
-| `search_all` | Search ALL indexed code across every directory. Same pointer format. |
-| `code_skeleton` | Collapsed file structure (~4x fewer tokens than reading the full file) |
-| `trace_calls` | Call graph — who calls a symbol and what it calls (unscoped, crosses project boundaries) |
-| `list_symbols` | List indexed functions, classes, and types with definition locations |
-| `index_status` | Check index health: chunk counts, indexed directories, model info |
+| `semantic_search` | Code search by meaning. 16 composable params: query, limit, root, path, detail (pointer/code/full), context_lines, min_score, max_per_file, file, exclude, language, role, mode (symbol), include_imports, name_pattern. |
+| `search_all` | Search ALL indexed code. Same params + `projects`/`exclude_projects` to scope by project name. |
+| `code_skeleton` | Collapsed file structure (~4x fewer tokens). Accepts files, directories, or comma-separated paths. `format: "json"` for structured output. |
+| `trace_calls` | Call graph with importers, callers (multi-hop via `depth`), and callees with file:line locations. |
+| `list_symbols` | List indexed symbols with role (ORCH/DEF/IMPL) and export status. |
+| `summarize_project` | High-level project overview — languages, directory structure, roles, key symbols, entry points. |
+| `related_files` | Find dependencies and dependents of a file by shared symbol references. |
+| `recent_changes` | Recently modified indexed files with relative timestamps. |
+| `index_status` | Check index health: per-project chunk counts, model info, watcher status. |
 | `summarize_directory` | Generate LLM summaries for indexed chunks. Summaries appear in search results. |
 
 ## Commands
@@ -125,8 +128,17 @@ gmax "how is the database connection pooled?"
 | `-m <n>` | Max total results to return. | `5` |
 | `--per-file <n>` | Max matches to show per file. | `3` |
 | `-c`, `--content` | Show full chunk content instead of snippets. | `false` |
+| `-C <n>`, `--context <n>` | Include N lines before/after each result. | `0` |
 | `--scores` | Show relevance scores (0-1) for each result. | `false` |
 | `--min-score <n>` | Filter out results below this score threshold. | `0` |
+| `--root <dir>` | Search a different project directory. | cwd |
+| `--file <name>` | Filter to files matching this name (e.g. `syncer.ts`). | — |
+| `--exclude <prefix>` | Exclude files under this path prefix (e.g. `tests/`). | — |
+| `--lang <ext>` | Filter by file extension (e.g. `ts`, `py`). | — |
+| `--role <role>` | Filter by role: `ORCHESTRATION`, `DEFINITION`, `IMPLEMENTATION`. | — |
+| `--symbol` | Append call graph (importers, callers, callees) after results. | `false` |
+| `--imports` | Prepend file imports to each result. | `false` |
+| `--name <regex>` | Filter results by symbol name regex. | — |
 | `--compact` | Compact hits view (paths + line ranges + role/preview). | `false` |
 | `--skeleton` | Show code skeleton for matching files instead of snippets. | `false` |
 | `--plain` | Disable ANSI colors and use simpler formatting. | `false` |
@@ -136,10 +148,11 @@ gmax "how is the database connection pooled?"
 
 ```bash
 gmax "API rate limiting logic"
-gmax "error handling" --per-file 5
-gmax "user validation" --compact
-gmax "authentication" --scores --min-score 0.5
-gmax "database connection" --skeleton
+gmax "auth handler" --role ORCHESTRATION --lang ts --plain
+gmax "database" --file syncer.ts --plain
+gmax "VectorDB" --symbol --plain
+gmax "error handling" -C 5 --imports
+gmax "handler" --name "handle.*" --exclude tests/
 ```
 
 ### `gmax index`
@@ -182,18 +195,57 @@ gmax serve --background           # Background mode
 gmax serve --cpu                  # Force CPU-only embeddings
 ```
 
+### `gmax trace`
+
+Call graph — who imports a symbol, who calls it, and what it calls.
+
+```bash
+gmax trace handleAuth             # 1-hop trace
+gmax trace handleAuth -d 2        # 2-hop: callers-of-callers
+```
+
 ### `gmax skeleton`
 
-Compressed view of a file — signatures with bodies collapsed.
+Compressed view of a file — signatures with bodies collapsed. Supports files, directories, and batch.
 
 ```bash
-gmax skeleton src/lib/auth.ts
-gmax skeleton AuthService         # Find symbol, skeletonize its file
-gmax skeleton "auth logic"        # Search, skeletonize top matches
+gmax skeleton src/lib/auth.ts             # Single file
+gmax skeleton src/lib/search/             # All files in directory
+gmax skeleton src/a.ts,src/b.ts           # Batch
+gmax skeleton src/lib/auth.ts --json      # Structured JSON output
+gmax skeleton AuthService                 # Find symbol, skeletonize its file
 ```
 
 **Supported Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP, Swift, Kotlin.
 
+### `gmax project`
+
+High-level project overview — languages, directory structure, role distribution, key symbols, entry points.
+
+```bash
+gmax project                     # Current project
+gmax project --root ~/workspace  # Different project
+```
+
+### `gmax related`
+
+Find files related by shared symbol references — dependencies and dependents.
+
+```bash
+gmax related src/lib/index/syncer.ts
+gmax related src/commands/mcp.ts -l 5
+```
+
+### `gmax recent`
+
+Show recently modified indexed files with relative timestamps.
+
+```bash
+gmax recent                      # Last 20 modified files
+gmax recent -l 10                # Last 10
+gmax recent --root ~/workspace   # Different project
+```
+
 ### `gmax config`
 
 View or update configuration without the full interactive setup.

package/dist/commands/search.js

@@ -357,7 +357,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;
+    var _a, _b, _c, _d, _e;
     const options = cmd.optsWithGlobals();
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
@@ -497,10 +497,23 @@ Examples:
                 throw e;
             }
         }
+        // Ensure a watcher is running for live reindexing
+        if (!process.env.VITEST && !((_c = process.env.NODE_ENV) === null || _c === void 0 ? void 0 : _c.includes("test"))) {
+            try {
+                const { execFileSync } = yield Promise.resolve().then(() => __importStar(require("node:child_process")));
+                execFileSync("gmax", ["watch", "-b", "--path", projectRoot], {
+                    timeout: 5000,
+                    stdio: "ignore",
+                });
+            }
+            catch (_f) {
+                // Watcher may already be running — ignore
+            }
+        }
         const searcher = new searcher_1.Searcher(vectorDb);
         // Use --root or fall back to project root
         const effectiveRoot = options.root
-            ? (_c = (0, project_root_1.findProjectRoot)(path.resolve(options.root))) !== null && _c !== void 0 ? _c : path.resolve(options.root)
+            ? (_d = (0, project_root_1.findProjectRoot)(path.resolve(options.root))) !== null && _d !== void 0 ? _d : path.resolve(options.root)
             : projectRoot;
         const searchPathPrefix = exec_path
             ? path.resolve(exec_path)
@@ -519,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 ((_d = searchResult.warnings) === null || _d === void 0 ? void 0 : _d.length) {
+        if ((_e = searchResult.warnings) === null || _e === void 0 ? void 0 : _e.length) {
             for (const w of searchResult.warnings) {
                 console.warn(`Warning: ${w}`);
             }
@@ -536,7 +549,7 @@ Examples:
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_e) {
+            catch (_g) {
                 // Invalid regex — skip
             }
         }
@@ -621,7 +634,7 @@ Examples:
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_f) {
+            catch (_h) {
                 // Trace failed — skip silently
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.7.22",
+  "version": "0.7.24",
   "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.22",
+  "version": "0.7.24",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

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

@@ -130,11 +130,31 @@ The watcher auto-starts when the MCP server connects — it detects file changes
 
 If search results include a warning like "Full-text search unavailable", results may be less precise. This resolves automatically — the index retries FTS every 5 minutes.
 
+## CLI vs MCP — when to use which
+
+**Prefer CLI (`Bash(gmax ...)`) for repeated searches.** The CLI is ~2x more token-efficient because MCP tool schemas add ~800 tokens of overhead per call. Every CLI flag maps to an MCP param:
+
+```
+Bash(gmax "auth handler" --role ORCHESTRATION --lang ts --plain -m 3)
+```
+
+is equivalent to `semantic_search` with `role: "ORCHESTRATION", language: "ts", limit: 3` — but costs half the tokens.
+
+**CLI commands for all MCP tools:**
+- `gmax "query" --plain` → `semantic_search`
+- `gmax trace <symbol> -d 2` → `trace_calls` with depth
+- `gmax skeleton <target> --json` → `code_skeleton`
+- `gmax project` → `summarize_project`
+- `gmax related <file>` → `related_files`
+- `gmax recent` → `recent_changes`
+
+**Use MCP tools when:** first exploring (tool descriptions guide usage), or when you need pointer mode output (more structured than CLI).
+
 ## Tips
 
 - **Be specific.** "auth" returns noise. "where does the server validate JWT tokens from the Authorization header" returns exactly what you need. Aim for 5+ words.
-- **ORCH results contain the logic** — prioritize over DEF/IMPL results.
+- **Use `--plain` for CLI searches** — agent-friendly output without ANSI codes.
+- **ORCH results contain the logic** — use `--role ORCHESTRATION` to filter noise.
 - **Summaries tell you what the code does** without reading it. Use them to decide what to `Read`.
-- **Use `root` for cross-project search** — absolute path to another indexed directory.
-- **Use `max_per_file`** when results cluster in one file but you need diversity.
+- **Use `--symbol` on CLI** to get search results + call graph in one shot.
 - **Don't search for exact strings** — use grep/Grep for that. gmax finds concepts, not literals.