grepmax 0.9.3 → 0.9.5

package/README.md

@@ -186,16 +186,17 @@ gmax index --reset                # Full re-index from scratch
 
 ### `gmax watch`
 
-Background file watcher for live reindexing. Watches for file changes and incrementally updates the centralized index. Uses FSEvents on macOS (kernel-level, low overhead) and polling on Linux.
+Background file watcher for live reindexing. A single daemon process watches all registered projects through native OS file system events (`@parcel/watcher` — FSEvents on macOS, inotify on Linux). File changes are detected in sub-second and incrementally reindexed.
 
 ```bash
-gmax watch -b                     # Background mode (auto-stops after 30min idle)
-gmax watch --path ~/workspace     # Watch a specific directory
-gmax watch status                 # Show running watchers
-gmax watch stop --all             # Stop all watchers
+gmax watch --daemon -b            # Start daemon (watches all projects)
+gmax watch -b                     # Per-project mode (fallback)
+gmax watch status                 # Show daemon + watcher status
+gmax watch stop                   # Stop daemon
+gmax watch stop --all             # Stop everything
 ```
 
-The MCP server auto-starts a watcher on session start. You rarely need to run this manually.
+The daemon auto-starts when you run `gmax search` or use MCP tools. It shuts down after 30 minutes of inactivity. CLI commands communicate with the daemon over a Unix domain socket at `~/.gmax/daemon.sock`.
 
 ### `gmax summarize`
 
@@ -295,6 +296,9 @@ gmax doctor
 All data lives in `~/.gmax/`:
 - `~/.gmax/lancedb/` — LanceDB vector store (one database for all indexed directories)
 - `~/.gmax/cache/meta.lmdb` — file metadata cache (content hashes, mtimes)
+- `~/.gmax/cache/watchers.lmdb` — watcher/daemon registry (LMDB, crash-safe)
+- `~/.gmax/daemon.sock` — Unix domain socket for daemon IPC
+- `~/.gmax/logs/` — daemon and watcher logs (5MB rotation)
 - `~/.gmax/config.json` — global config (model tier, embed mode)
 - `~/.gmax/models/` — embedding models
 - `~/.gmax/grammars/` — Tree-sitter grammars
@@ -304,6 +308,10 @@ All chunks store **absolute file paths**. Search scoping is done via path prefix
 
 ### Performance
 
+- **Single Daemon:** One process watches all projects via native OS events — no polling, sub-second file change detection. Shared VectorDB, MetaCache, and worker pool across projects.
+- **Native File Watching:** `@parcel/watcher` uses FSEvents (macOS), inotify (Linux), ReadDirectoryChangesW (Windows) — zero CPU overhead, no file descriptor exhaustion.
+- **Automatic Compaction:** LanceDB table fragments from incremental inserts are compacted every 5 minutes, preventing performance degradation over time.
+- **LMDB Caching:** File metadata reads use LRU/LFU caching for the watcher's hot path.
 - **Bounded Concurrency:** Worker threads scale to 50% of CPU cores (min 4). Override with `GMAX_WORKER_THREADS`.
 - **Smart Chunking:** `tree-sitter` splits code by function/class boundaries for complete logical blocks.
 - **Deduplication:** Identical code blocks are embedded once and cached.
@@ -389,11 +397,12 @@ See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture det
 
 ## Troubleshooting
 
-- **Index feels stale?** Run `gmax index` to refresh, or use `gmax watch -b` for live reindexing.
+- **Index feels stale?** Run `gmax index` to refresh. The daemon auto-reindexes on file changes.
 - **Weird results?** Run `gmax doctor` to verify models.
 - **Index getting stuck?** Run `gmax index --verbose` to see which file is being processed.
 - **Need a fresh start?** `rm -rf ~/.gmax/lancedb ~/.gmax/cache` then `gmax index`.
-- **MLX server won't start?** Check `/tmp/mlx-embed-server.log` for errors. Use `GMAX_EMBED_MODE=cpu` to fall back to CPU.
+- **Daemon issues?** Check `~/.gmax/logs/daemon.log`. Run `gmax watch stop` then `gmax watch --daemon -b` to restart.
+- **MLX server won't start?** Check `~/.gmax/logs/mlx-embed-server.log` for errors. Use `GMAX_EMBED_MODE=cpu` to fall back to CPU.
 
 ## Attribution
 

package/dist/commands/mcp.js

@@ -441,7 +441,7 @@ exports.mcp = new commander_1.Command("mcp")
                 }
                 const result = yield searcher.search(query, limit, { rerank: true }, Object.keys(filters).length > 0 ? filters : undefined, pathPrefix);
                 if (!result.data || result.data.length === 0) {
-                    return ok("No matches found.");
+                    return ok("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed.");
                 }
                 const minScore = typeof args.min_score === "number" ? args.min_score : 0;
                 const maxPerFile = typeof args.max_per_file === "number" ? args.max_per_file : 0;
@@ -743,7 +743,7 @@ exports.mcp = new commander_1.Command("mcp")
                 const depth = Math.min(Math.max(Number(args.depth) || 1, 1), 3);
                 const graph = yield builder.buildGraphMultiHop(symbol, depth);
                 if (!graph.center) {
-                    return ok(`Symbol '${symbol}' not found in the index.`);
+                    return ok(`Symbol '${symbol}' not found in the index. Check \`gmax status\` to see which projects are indexed, or try \`gmax search ${symbol}\` to find similar symbols.`);
                 }
                 const lines = [];
                 // Center
@@ -870,7 +870,7 @@ exports.mcp = new commander_1.Command("mcp")
                 })
                     .slice(0, limit);
                 if (entries.length === 0) {
-                    return ok("No symbols found. Run 'gmax index' to build the index.");
+                    return ok("No symbols found. Run `gmax status` to verify the project is indexed, or `gmax index` to rebuild.");
                 }
                 const lines = entries.map((e) => {
                     const rel = e.path.startsWith(projectRoot)
@@ -1118,7 +1118,7 @@ exports.mcp = new commander_1.Command("mcp")
                     .where(`path = '${(0, filter_builder_1.escapeSqlString)(absPath)}'`)
                     .toArray();
                 if (fileChunks.length === 0) {
-                    return ok(`File not found in index: ${file}`);
+                    return ok(`File not found in index: ${file}. Check that the path is relative to the project root. Run \`gmax status\` to see indexed projects.`);
                 }
                 const definedHere = new Set();
                 const referencedHere = new Set();
@@ -1236,7 +1236,7 @@ exports.mcp = new commander_1.Command("mcp")
                     files.sort((a, b) => b.mtimeMs - a.mtimeMs);
                     const top = files.slice(0, limit);
                     if (top.length === 0) {
-                        return ok(`No indexed files found for ${root}`);
+                        return ok(`No indexed files found for ${root}. Run \`gmax add\` to register and index this project.`);
                     }
                     const now = Date.now();
                     const lines = [

package/dist/commands/project.js

@@ -59,8 +59,9 @@ function toArr(val) {
 exports.project = new commander_1.Command("project")
     .description("Show project overview — languages, structure, key symbols")
     .option("--root <dir>", "Project root (defaults to current directory)")
+    .option("--agent", "Compact output for AI agents", false)
     .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     let vectorDb = null;
     try {
         const root = opts.root
@@ -86,6 +87,7 @@ exports.project = new commander_1.Command("project")
             .toArray();
         if (rows.length === 0) {
             console.log(`No indexed data found for ${root}. Run: gmax index --path ${root}`);
+            process.exitCode = 1;
             return;
         }
         const files = new Set();
@@ -128,33 +130,50 @@ exports.project = new commander_1.Command("project")
         }
         const projects = (0, project_registry_1.listProjects)();
         const proj = projects.find((p) => p.root === root);
-        console.log(`Project: ${projectName} (${root})`);
-        console.log(`Last indexed: ${(_c = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _c !== void 0 ? _c : "unknown"} • ${rows.length} chunks • ${files.size} files\n`);
         const extEntries = Array.from(extCounts.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, 8);
-        console.log(`Languages: ${extEntries.map(([ext, count]) => `${ext} (${Math.round((count / rows.length) * 100)}%)`).join(", ")}\n`);
-        console.log("Directory structure:");
-        for (const [dir, data] of Array.from(dirCounts.entries())
-            .sort((a, b) => b[1].chunks - a[1].chunks)
-            .slice(0, 12)) {
-            console.log(`  ${dir.padEnd(25)} (${data.files.size} files, ${data.chunks} chunks)`);
-        }
-        const roleEntries = Array.from(roleCounts.entries()).sort((a, b) => b[1] - a[1]);
-        console.log(`\nRoles: ${roleEntries.map(([r, c]) => `${Math.round((c / rows.length) * 100)}% ${r}`).join(", ")}\n`);
         const topSymbols = Array.from(symbolRefs.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, 8);
-        if (topSymbols.length > 0) {
-            console.log("Key symbols (by reference count):");
-            for (const [sym, count] of topSymbols) {
-                console.log(`  ${sym.padEnd(25)} (referenced ${count}x)`);
+        if (opts.agent) {
+            console.log(`name\t${projectName}`);
+            console.log(`root\t${root}`);
+            console.log(`chunks\t${rows.length}`);
+            console.log(`files\t${files.size}`);
+            console.log(`last_indexed\t${(_c = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _c !== void 0 ? _c : "unknown"}`);
+            console.log(`languages\t${extEntries.map(([ext]) => ext).join(",")}`);
+            console.log(`top_dirs\t${Array.from(dirCounts.entries()).sort((a, b) => b[1].chunks - a[1].chunks).slice(0, 8).map(([d]) => d).join(",")}`);
+            if (topSymbols.length > 0) {
+                console.log(`key_symbols\t${topSymbols.map(([s]) => s).join(",")}`);
+            }
+            if (entryPoints.length > 0) {
+                console.log(`entry_points\t${entryPoints.slice(0, 10).map((e) => e.symbol).join(",")}`);
             }
         }
-        if (entryPoints.length > 0) {
-            console.log("\nEntry points (exported orchestration):");
-            for (const ep of entryPoints.slice(0, 10)) {
-                console.log(`  ${ep.symbol.padEnd(25)} ${ep.path}`);
+        else {
+            console.log(`Project: ${projectName} (${root})`);
+            console.log(`Last indexed: ${(_d = proj === null || proj === void 0 ? void 0 : proj.lastIndexed) !== null && _d !== void 0 ? _d : "unknown"} • ${rows.length} chunks • ${files.size} files\n`);
+            console.log(`Languages: ${extEntries.map(([ext, count]) => `${ext} (${Math.round((count / rows.length) * 100)}%)`).join(", ")}\n`);
+            console.log("Directory structure:");
+            for (const [dir, data] of Array.from(dirCounts.entries())
+                .sort((a, b) => b[1].chunks - a[1].chunks)
+                .slice(0, 12)) {
+                console.log(`  ${dir.padEnd(25)} (${data.files.size} files, ${data.chunks} chunks)`);
+            }
+            const roleEntries = Array.from(roleCounts.entries()).sort((a, b) => b[1] - a[1]);
+            console.log(`\nRoles: ${roleEntries.map(([r, c]) => `${Math.round((c / rows.length) * 100)}% ${r}`).join(", ")}\n`);
+            if (topSymbols.length > 0) {
+                console.log("Key symbols (by reference count):");
+                for (const [sym, count] of topSymbols) {
+                    console.log(`  ${sym.padEnd(25)} (referenced ${count}x)`);
+                }
+            }
+            if (entryPoints.length > 0) {
+                console.log("\nEntry points (exported orchestration):");
+                for (const ep of entryPoints.slice(0, 10)) {
+                    console.log(`  ${ep.symbol.padEnd(25)} ${ep.path}`);
+                }
             }
         }
     }
@@ -168,7 +187,7 @@ exports.project = new commander_1.Command("project")
             try {
                 yield vectorDb.close();
             }
-            catch (_d) { }
+            catch (_e) { }
         }
         yield (0, exit_1.gracefulExit)();
     }

package/dist/commands/recent.js

@@ -61,6 +61,7 @@ exports.recent = new commander_1.Command("recent")
     .description("Show recently modified indexed files")
     .option("-l, --limit <n>", "Max files (default 20)", "20")
     .option("--root <dir>", "Project root (defaults to current directory)")
+    .option("--agent", "Compact output for AI agents", false)
     .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, e_1, _b, _c;
     var _d, _e;
@@ -94,16 +95,28 @@ exports.recent = new commander_1.Command("recent")
             const top = files.slice(0, limit);
             if (top.length === 0) {
                 console.log(`No indexed files found for ${root}`);
+                console.log("\nTry: `gmax add` to register and index this project, or `gmax status` to see what's indexed.");
+                process.exitCode = 1;
                 return;
             }
             const now = Date.now();
-            console.log(`Recent changes in ${path.basename(root)} (${top.length} most recent):\n`);
-            for (const f of top) {
-                const rel = f.path.startsWith(prefix)
-                    ? f.path.slice(prefix.length)
-                    : f.path;
-                const ago = (0, format_helpers_1.formatTimeAgo)(now - f.mtimeMs);
-                console.log(`  ${ago.padEnd(10)} ${rel}`);
+            if (opts.agent) {
+                for (const f of top) {
+                    const rel = f.path.startsWith(prefix)
+                        ? f.path.slice(prefix.length)
+                        : f.path;
+                    console.log(`${rel}\t${(0, format_helpers_1.formatTimeAgo)(now - f.mtimeMs)}`);
+                }
+            }
+            else {
+                console.log(`Recent changes in ${path.basename(root)} (${top.length} most recent):\n`);
+                for (const f of top) {
+                    const rel = f.path.startsWith(prefix)
+                        ? f.path.slice(prefix.length)
+                        : f.path;
+                    const ago = (0, format_helpers_1.formatTimeAgo)(now - f.mtimeMs);
+                    console.log(`  ${ago.padEnd(10)} ${rel}`);
+                }
             }
         }
         finally {

package/dist/commands/related.js

@@ -60,6 +60,7 @@ exports.related = new commander_1.Command("related")
     .argument("<file>", "File path relative to project root")
     .option("-l, --limit <n>", "Max results per direction (default 10)", "10")
     .option("--root <dir>", "Project root directory")
+    .option("--agent", "Compact output for AI agents", false)
     .action((file, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const limit = Math.min(Math.max(Number.parseInt(opts.limit || "10", 10), 1), 25);
@@ -79,6 +80,8 @@ exports.related = new commander_1.Command("related")
             .toArray();
         if (fileChunks.length === 0) {
             console.log(`File not found in index: ${file}`);
+            console.log("\nCheck that the path is relative to the project root. Run `gmax status` to see indexed projects.");
+            process.exitCode = 1;
             return;
         }
         const definedHere = new Set();
@@ -123,37 +126,53 @@ exports.related = new commander_1.Command("related")
                 revCounts.set(p, (revCounts.get(p) || 0) + 1);
             }
         }
-        console.log(`Related files for ${file}:\n`);
         const topDeps = Array.from(depCounts.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, limit);
-        if (topDeps.length > 0) {
-            console.log("Dependencies (files this imports/calls):");
-            for (const [p, count] of topDeps) {
-                const rel = p.startsWith(`${projectRoot}/`)
-                    ? p.slice(projectRoot.length + 1)
-                    : p;
-                console.log(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
-            }
-        }
-        else {
-            console.log("Dependencies: none found");
-        }
-        console.log("");
         const topRevs = Array.from(revCounts.entries())
             .sort((a, b) => b[1] - a[1])
             .slice(0, limit);
-        if (topRevs.length > 0) {
-            console.log("Dependents (files that call this):");
+        if (opts.agent) {
+            const rel = (p) => p.startsWith(`${projectRoot}/`)
+                ? p.slice(projectRoot.length + 1)
+                : p;
+            for (const [p, count] of topDeps) {
+                console.log(`dep: ${rel(p)}\t${count}`);
+            }
             for (const [p, count] of topRevs) {
-                const rel = p.startsWith(`${projectRoot}/`)
-                    ? p.slice(projectRoot.length + 1)
-                    : p;
-                console.log(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
+                console.log(`rev: ${rel(p)}\t${count}`);
+            }
+            if (!topDeps.length && !topRevs.length) {
+                console.log("(none)");
             }
         }
         else {
-            console.log("Dependents: none found");
+            console.log(`Related files for ${file}:\n`);
+            if (topDeps.length > 0) {
+                console.log("Dependencies (files this imports/calls):");
+                for (const [p, count] of topDeps) {
+                    const rel = p.startsWith(`${projectRoot}/`)
+                        ? p.slice(projectRoot.length + 1)
+                        : p;
+                    console.log(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
+                }
+            }
+            else {
+                console.log("Dependencies: none found");
+            }
+            console.log("");
+            if (topRevs.length > 0) {
+                console.log("Dependents (files that call this):");
+                for (const [p, count] of topRevs) {
+                    const rel = p.startsWith(`${projectRoot}/`)
+                        ? p.slice(projectRoot.length + 1)
+                        : p;
+                    console.log(`  ${rel.padEnd(40)} (${count} shared symbol${count > 1 ? "s" : ""})`);
+                }
+            }
+            else {
+                console.log("Dependents: none found");
+            }
         }
     }
     catch (error) {

package/dist/commands/search.js

@@ -272,6 +272,8 @@ function outputSkeletons(results, projectRoot, limit, db) {
         }
         if (filesToProcess.length === 0) {
             console.log("No skeleton matches found.");
+            console.log("\nTry: broaden your query, or use `gmax skeleton <path>` to view a specific file's structure.");
+            process.exitCode = 1;
             return;
         }
         // Reuse or init skeletonizer for fallbacks
@@ -326,6 +328,19 @@ function outputSkeletons(results, projectRoot, limit, db) {
         }
     });
 }
+function resultCountHeader(results, maxCount) {
+    var _a, _b, _c;
+    const files = new Set();
+    for (const r of results) {
+        const p = (_c = (_a = r.path) !== null && _a !== void 0 ? _a : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _c !== void 0 ? _c : "";
+        if (p)
+            files.add(p);
+    }
+    const showing = results.length < maxCount
+        ? `${results.length}`
+        : `top ${results.length}`;
+    return `Found ${results.length} match${results.length === 1 ? "" : "es"} (showing ${showing}) across ${files.size} file${files.size === 1 ? "" : "s"}`;
+}
 exports.search = new commander_1.Command("search")
     .description("Search code by meaning (default command)")
     .option("-m <max_count>, --max-count <max_count>", "The maximum number of results to return (total)", "5")
@@ -403,21 +418,31 @@ Examples:
                     ? toCompactHits(filteredData)
                     : [];
                 if (options.compact) {
-                    const compactText = compactHits.length
-                        ? formatCompactTable(compactHits, projectRootForServer, pattern, {
+                    if (!compactHits.length) {
+                        console.log("No matches found.");
+                        console.log("\nTry: broaden your query, use fewer keywords, or check `gmax status` to verify the project is indexed.");
+                        process.exitCode = 1;
+                    }
+                    else {
+                        console.log(formatCompactTable(compactHits, projectRootForServer, pattern, {
                             isTTY: !!process.stdout.isTTY,
                             plain: !!options.plain,
-                        })
-                        : "No matches found.";
-                    console.log(compactText);
+                        }));
+                    }
                     return; // EXIT
                 }
                 if (!filteredData.length) {
                     console.log("No matches found.");
+                    console.log("\nTry: broaden your query, use fewer keywords, or check `gmax status` to verify the project is indexed.");
+                    process.exitCode = 1;
                     return; // EXIT
                 }
                 const isTTY = process.stdout.isTTY;
                 const shouldBePlain = options.plain || !isTTY;
+                if (!options.agent && !options.compact) {
+                    console.log(resultCountHeader(filteredData, parseInt(options.m, 10)));
+                    console.log();
+                }
                 if (shouldBePlain) {
                     const mappedResults = toTextResults(filteredData);
                     const output = (0, formatter_1.formatTextResults)(mappedResults, pattern, projectRootForServer, {
@@ -592,6 +617,7 @@ Examples:
         if (options.agent) {
             if (!filteredData.length) {
                 console.log("(none)");
+                process.exitCode = 1;
             }
             else {
                 // In agent mode, print imports header per file
@@ -685,25 +711,26 @@ Examples:
             yield outputSkeletons(filteredData, projectRoot, parseInt(options.m, 10), vectorDb);
             return;
         }
-        const compactHits = options.compact ? toCompactHits(filteredData) : [];
-        const compactText = options.compact && compactHits.length
-            ? formatCompactTable(compactHits, projectRoot, pattern, {
-                isTTY: !!process.stdout.isTTY,
-                plain: !!options.plain,
-            })
-            : options.compact
-                ? "No matches found."
-                : "";
         if (!filteredData.length) {
             console.log("No matches found.");
+            console.log("\nTry: broaden your query, use fewer keywords, or check `gmax status` to verify the project is indexed.");
+            process.exitCode = 1;
             return;
         }
         if (options.compact) {
-            console.log(compactText);
+            const compactHits = toCompactHits(filteredData);
+            console.log(formatCompactTable(compactHits, projectRoot, pattern, {
+                isTTY: !!process.stdout.isTTY,
+                plain: !!options.plain,
+            }));
             return;
         }
         const isTTY = process.stdout.isTTY;
         const shouldBePlain = options.plain || !isTTY;
+        if (!options.agent && !options.compact) {
+            console.log(resultCountHeader(filteredData, parseInt(options.m, 10)));
+            console.log();
+        }
         // Print imports per unique file before results when --imports is used
         if (options.imports) {
             const seenFiles = new Set();

package/dist/commands/skeleton.js

@@ -63,7 +63,20 @@ const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
 const vector_db_1 = require("../lib/store/vector-db");
 const file_utils_1 = require("../lib/utils/file-utils");
 const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
+/**
+ * Resolve a relative path across all indexed projects.
+ * Returns the first match found, or null.
+ */
+function resolveAcrossProjects(relativePath) {
+    for (const project of (0, project_registry_1.listProjects)()) {
+        const candidate = path.join(project.root, relativePath);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
 /**
  * Check if target looks like a file path.
  */
@@ -185,11 +198,16 @@ Examples:
         }
         if (isFilePath(target)) {
             // === FILE MODE ===
-            const filePath = path.resolve(target);
+            let filePath = path.resolve(target);
             if (!fs.existsSync(filePath)) {
-                console.error(`File not found: ${filePath}`);
-                process.exitCode = 1;
-                return;
+                // Try resolving across indexed projects
+                const found = resolveAcrossProjects(target);
+                if (!found) {
+                    console.error(`File not found: ${filePath}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                filePath = found;
             }
             if (vectorDb) {
                 // Use absolute path for DB lookup (centralized index stores absolute paths)

package/dist/commands/status.js

@@ -91,21 +91,50 @@ function formatChunks(n) {
 }
 exports.status = new commander_1.Command("status")
     .description("Show gmax index status for all projects")
+    .option("--agent", "Compact output for AI agents", false)
     .addHelpText("after", `
 Examples:
   gmax status              Show status of all indexed projects
 `)
-    .action(() => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
+    .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
     const globalConfig = (0, index_config_1.readGlobalConfig)();
     const projects = (0, project_registry_1.listProjects)();
     (0, watcher_store_1.listWatchers)(); // cleans stale entries as side effect
     const indexing = (0, lock_1.isLocked)(config_1.PATHS.globalRoot);
     const currentRoot = (0, project_root_1.findProjectRoot)(process.cwd());
-    // Header
-    console.log(`\n${style.bold("gmax")} · ${globalConfig.modelTier} (${globalConfig.vectorDim}d, ${globalConfig.embedMode})${indexing ? style.yellow(" · indexing...") : ""}`);
+    if (!opts.agent) {
+        // Header
+        console.log(`\n${style.bold("gmax")} · ${globalConfig.modelTier} (${globalConfig.vectorDim}d, ${globalConfig.embedMode})${indexing ? style.yellow(" · indexing...") : ""}`);
+    }
     if (projects.length === 0) {
-        console.log(`\nNo projects added yet. Run ${style.cyan("gmax add")} to get started.\n`);
+        if (opts.agent) {
+            console.log("(none)");
+        }
+        else {
+            console.log(`\nNo projects added yet. Run ${style.cyan("gmax add")} to get started.\n`);
+        }
+        yield (0, exit_1.gracefulExit)();
+        return;
+    }
+    if (opts.agent) {
+        for (const project of projects) {
+            const watcher = (0, watcher_store_1.getWatcherForProject)(project.root);
+            const projectStatus = (_a = project.status) !== null && _a !== void 0 ? _a : "indexed";
+            let st;
+            if (projectStatus === "pending")
+                st = "pending";
+            else if (projectStatus === "error")
+                st = "error";
+            else if ((watcher === null || watcher === void 0 ? void 0 : watcher.status) === "syncing")
+                st = "indexing";
+            else if (watcher)
+                st = "watching";
+            else
+                st = "idle";
+            const isCurrent = project.root === currentRoot;
+            console.log(`${project.name}\t${formatChunks(project.chunkCount)}\t${formatAge(project.lastIndexed)}\t${st}${isCurrent ? "\tcurrent" : ""}`);
+        }
         yield (0, exit_1.gracefulExit)();
         return;
     }
@@ -117,7 +146,7 @@ Examples:
         const watcher = (0, watcher_store_1.getWatcherForProject)(project.root);
         // Status column
         let statusStr;
-        const projectStatus = (_a = project.status) !== null && _a !== void 0 ? _a : "indexed";
+        const projectStatus = (_b = project.status) !== null && _b !== void 0 ? _b : "indexed";
         if (projectStatus === "pending") {
             statusStr = style.yellow("pending");
         }

package/dist/commands/symbols.js

@@ -123,7 +123,13 @@ function collectSymbols(options) {
 }
 function formatTable(entries) {
     if (entries.length === 0) {
-        return "No symbols found. Run `gmax index` to build the index.";
+        return [
+            "No symbols found.",
+            "",
+            "Try:",
+            "  gmax status   — verify the project is indexed",
+            "  gmax index    — rebuild the index",
+        ].join("\n");
     }
     const rows = entries.map((e) => ({
         symbol: e.symbol,
@@ -147,12 +153,25 @@ function formatTable(entries) {
     ];
     return lines.join("\n");
 }
+function formatAgent(entries, projectRoot) {
+    if (entries.length === 0)
+        return "(none)";
+    return entries
+        .map((e) => {
+        const rel = e.path.startsWith(projectRoot)
+            ? e.path.slice(projectRoot.length + 1)
+            : e.path;
+        return `${e.symbol}\t${rel}:${Math.max(1, e.line + 1)}\t${e.count}`;
+    })
+        .join("\n");
+}
 exports.symbols = new commander_1.Command("symbols")
     .description("List indexed symbols and where they are defined")
     .argument("[pattern]", "Optional pattern to filter symbols by name")
     .option("-l, --limit <number>", "Max symbols to list (default 20)", "20")
     .option("-p, --path <prefix>", "Only include symbols under this path prefix")
     .option("--root <dir>", "Project root directory")
+    .option("--agent", "Compact output for AI agents", false)
     .action((pattern, cmd) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b;
     const root = cmd.root ? path.resolve(cmd.root) : process.cwd();
@@ -166,6 +185,14 @@ exports.symbols = new commander_1.Command("symbols")
         pathPrefix,
         pattern: pattern,
     });
-    console.log(`${style.bold("Project")}: ${style.green(projectRoot)}\n${formatTable(entries)}`);
+    if (cmd.agent) {
+        console.log(formatAgent(entries, projectRoot));
+    }
+    else {
+        console.log(`${style.bold("Project")}: ${style.green(projectRoot)}\n${formatTable(entries)}`);
+    }
+    if (entries.length === 0) {
+        process.exitCode = 1;
+    }
     yield (0, exit_1.gracefulExit)();
 }));

package/dist/commands/trace.js

@@ -50,11 +50,35 @@ const formatter_1 = require("../lib/output/formatter");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
 const project_root_1 = require("../lib/utils/project-root");
+function formatTraceAgent(graph, projectRoot) {
+    if (!graph.center)
+        return "(not found)";
+    const rel = (p) => p.startsWith(projectRoot) ? p.slice(projectRoot.length + 1) : p;
+    const lines = [];
+    lines.push(`${graph.center.symbol}\t${rel(graph.center.file)}:${graph.center.line}\t${graph.center.role}`);
+    function walkCallers(tree, depth) {
+        for (const t of tree) {
+            lines.push(`${"  ".repeat(depth)}<- ${t.node.symbol}\t${rel(t.node.file)}:${t.node.line}`);
+            walkCallers(t.callers, depth + 1);
+        }
+    }
+    walkCallers(graph.callerTree, 0);
+    for (const c of graph.callees) {
+        if (c.file) {
+            lines.push(`-> ${c.symbol}\t${rel(c.file)}:${c.line}`);
+        }
+        else {
+            lines.push(`-> ${c.symbol}\t(not indexed)`);
+        }
+    }
+    return lines.join("\n");
+}
 exports.trace = new commander_1.Command("trace")
     .description("Trace the call graph for a symbol")
     .argument("<symbol>", "The symbol to trace")
     .option("-d, --depth <n>", "Caller traversal depth (default 1, max 3)", "1")
     .option("--root <dir>", "Project root directory")
+    .option("--agent", "Compact output for AI agents", false)
     .action((symbol, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
@@ -66,7 +90,15 @@ exports.trace = new commander_1.Command("trace")
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
         const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, projectRoot);
         const graph = yield graphBuilder.buildGraphMultiHop(symbol, depth);
-        console.log((0, formatter_1.formatTrace)(graph));
+        if (opts.agent) {
+            console.log(formatTraceAgent(graph, projectRoot));
+        }
+        else {
+            console.log((0, formatter_1.formatTrace)(graph, { symbol }));
+        }
+        if (!graph.center) {
+            process.exitCode = 1;
+        }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";

package/dist/lib/output/formatter.js

@@ -125,9 +125,23 @@ function formatResults(results, root, options = {}) {
         return "No results found.";
     return results.map((r) => formatResult(r, root, options)).join("\n\n");
 }
-function formatTrace(graph) {
+function formatTrace(graph, options) {
+    var _a;
     if (!graph.center) {
-        return style.dim("Symbol not found.");
+        const name = (_a = options === null || options === void 0 ? void 0 : options.symbol) !== null && _a !== void 0 ? _a : "unknown";
+        const lines = [
+            `Symbol not found: ${style.bold(name)}`,
+            "",
+            style.dim("Possible reasons:"),
+            style.dim("  • The symbol doesn't exist in any indexed project"),
+            style.dim("  • The containing file hasn't been indexed yet"),
+            style.dim("  • The name is spelled differently in the source"),
+            "",
+            style.dim("Try:"),
+            style.dim("  gmax status          — see which projects are indexed"),
+            style.dim("  gmax search <name>   — fuzzy search for similar symbols"),
+        ];
+        return lines.join("\n");
     }
     const lines = [];
     // 1. Importers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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.9.3",
+  "version": "0.9.5",
   "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

@@ -121,7 +121,7 @@ async function main() {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
       additionalContext:
-        '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. Bash(gmax status) to check indexed projects. Use --agent flag on search commands only. If search says "not added yet", run Bash(gmax add).',
+        '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. Bash(gmax status) to check indexed projects. --agent flag works on search, trace, symbols, related, recent, status, project. If search says "not added yet", run Bash(gmax add).',
     },
   };
   process.stdout.write(JSON.stringify(response));

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

@@ -40,7 +40,7 @@ If search returns "This project hasn't been added to gmax yet", run `Bash(gmax a
 
 ### Search — `gmax "query" --agent`
 
-The `--agent` flag is **search-only**. Do NOT use it on `trace`, `skeleton`, or other commands.
+The `--agent` flag produces compact, token-efficient output for AI agents. It is supported on: `search`, `trace`, `symbols`, `related`, `recent`, `status`, and `project`.
 
 ```
 gmax "where do we handle authentication" --agent
@@ -70,6 +70,7 @@ This shows function signatures, what each calls, and complexity — enough to de
 gmax trace handleAuth                      # 1-hop: callers + callees
 gmax trace handleAuth -d 2                 # 2-hop: callers-of-callers
 gmax trace handleAuth --root ~/project     # trace in a different project
+gmax trace handleAuth --agent              # compact: symbol\tpath:line, <- callers, -> callees
 ```
 
 ### Skeleton — `gmax skeleton <target>`
@@ -97,11 +98,20 @@ gmax related src/lib/index/syncer.ts --root ~/project
 gmax recent                                # recently modified files
 ```
 
-### Other
+### Symbols — `gmax symbols`
 ```
 gmax symbols                               # list indexed symbols
 gmax symbols auth -p src/ --root ~/proj    # filter by name, path, project
+gmax symbols --agent                       # compact: symbol\tpath:line\tcount
+```
+
+### Other
+```
 gmax status                                # show all indexed projects
+gmax status --agent                        # compact: name\tchunks\tage\tstatus
+gmax recent --agent                        # compact: path\tage
+gmax related src/file.ts --agent           # compact: dep:/rev: path\tcount
+gmax project --agent                       # compact: key\tvalue pairs
 gmax index                                 # reindex current directory
 gmax config                                # view/change settings
 gmax doctor                                # health check
@@ -124,7 +134,7 @@ Use MCP only for `index_status` and `summarize_directory`. Use CLI for everythin
 
 ## Tips
 
-- **Use `--agent` on search only** — one line per result with signature hints.
+- **Use `--agent` for compact output** — supported on search, trace, symbols, related, recent, status, project.
 - **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.