grepmax 0.4.0 → 0.5.0

package/README.md

@@ -24,7 +24,8 @@ Natural-language search that works like `grep`. Fast, local, and built for codin
 - **Role Detection:** Distinguishes `ORCHESTRATION` (high-level logic) from `DEFINITION` (types/classes).
 - **Local & Private:** 100% local embeddings via ONNX (CPU) or MLX (Apple Silicon GPU).
 - **Centralized Index:** One database at `~/.gmax/` — index once, search from anywhere.
-- **Agent-Ready:** Native output with symbols, roles, and call graphs.
+- **LLM Summaries:** Optional Qwen3-Coder generates one-line descriptions per code chunk at index time.
+- **Agent-Ready:** Pointer mode returns metadata (symbol, role, calls, summary) — no code snippets, ~80% fewer tokens.
 
 ## Quick Start
 
@@ -99,8 +100,8 @@ In our public benchmarks, `grepmax` can save about 20% of your LLM tokens and de
 
 | Tool | Description |
 | --- | --- |
-| `semantic_search` | Natural language code search. Use `root` to search a parent or sibling directory. |
-| `search_all` | Search ALL indexed code across every directory. |
+| `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 |
@@ -228,6 +229,19 @@ On Macs with Apple Silicon, gmax defaults to MLX for GPU-accelerated embeddings.
 
 To force CPU mode: `GMAX_EMBED_MODE=cpu gmax index`
 
+### LLM Summaries
+
+gmax can generate one-line natural language descriptions for every code chunk using a local LLM (Qwen3-Coder-30B-A3B via MLX). Summaries are pre-computed at index time and stored in LanceDB — zero latency at search time.
+
+The summarizer server runs on port `8101` and auto-starts alongside the embed server. If unavailable, indexing proceeds without summaries.
+
+Example search output with summaries:
+```
+handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
+  Validates JWT from Authorization header, checks RBAC permissions, returns 401 on failure
+  parent:AuthController calls:validateToken,checkRole,respond
+```
+
 ## Configuration
 
 ### Ignoring Files

package/dist/commands/doctor.js

@@ -48,16 +48,17 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const index_config_1 = require("../lib/index/index-config");
 const exit_1 = require("../lib/utils/exit");
 const project_root_1 = require("../lib/utils/project-root");
 exports.doctor = new commander_1.Command("doctor")
     .description("Check gmax health and paths")
     .action(() => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
     console.log("🏥 gmax Doctor\n");
     const root = config_1.PATHS.globalRoot;
     const models = config_1.PATHS.models;
     const grammars = config_1.PATHS.grammars;
-    const modelIds = [config_1.MODEL_IDS.embed, config_1.MODEL_IDS.colbert];
     const checkDir = (name, p) => {
         const exists = fs.existsSync(p);
         const symbol = exists ? "✅" : "❌";
@@ -66,18 +67,20 @@ exports.doctor = new commander_1.Command("doctor")
     checkDir("Root", root);
     checkDir("Models", models);
     checkDir("Grammars", grammars);
-    const modelStatuses = modelIds.map((id) => {
+    const globalConfig = (0, index_config_1.readGlobalConfig)();
+    const tier = (_a = config_1.MODEL_TIERS[globalConfig.modelTier]) !== null && _a !== void 0 ? _a : config_1.MODEL_TIERS.small;
+    const embedModel = globalConfig.embedMode === "gpu" ? tier.mlxModel : tier.onnxModel;
+    console.log(`\nEmbed mode: ${globalConfig.embedMode} | Model tier: ${globalConfig.modelTier} (${tier.vectorDim}d)`);
+    console.log(`Embed model: ${embedModel}`);
+    console.log(`ColBERT model: ${config_1.MODEL_IDS.colbert}`);
+    const modelStatuses = [embedModel, config_1.MODEL_IDS.colbert].map((id) => {
         const modelPath = path.join(models, ...id.split("/"));
         return { id, path: modelPath, exists: fs.existsSync(modelPath) };
     });
-    modelStatuses.forEach(({ id, path: p, exists }) => {
-        const symbol = exists ? "✅" : "❌";
-        console.log(`${symbol} Model: ${id} (${p})`);
+    modelStatuses.forEach(({ id, exists }) => {
+        const symbol = exists ? "✅" : "⚠️ ";
+        console.log(`${symbol} ${id}: ${exists ? "downloaded" : "will download on first use"}`);
     });
-    const missingModels = modelStatuses.filter(({ exists }) => !exists);
-    if (missingModels.length > 0) {
-        console.log("❌ Some models are missing; gmax will try bundled copies first, then download.");
-    }
     console.log(`\nLocal Project: ${process.cwd()}`);
     const projectRoot = (0, project_root_1.findProjectRoot)(process.cwd());
     if (projectRoot) {
@@ -87,6 +90,40 @@ exports.doctor = new commander_1.Command("doctor")
     else {
         console.log(`ℹ️  No index found in current directory (run 'gmax index' to create one)`);
     }
+    // Check MLX embed server
+    const embedUp = yield fetch("http://127.0.0.1:8100/health")
+        .then((r) => r.ok)
+        .catch(() => false);
+    console.log(`${embedUp ? "✅" : "⚠️ "} MLX Embed: ${embedUp ? "running (port 8100)" : "not running"}`);
+    // Check summarizer server
+    const summarizerUp = yield fetch("http://127.0.0.1:8101/health")
+        .then((r) => r.ok)
+        .catch(() => false);
+    console.log(`${summarizerUp ? "✅" : "⚠️ "} Summarizer: ${summarizerUp ? "running (port 8101)" : "not running"}`);
+    // Check summary coverage
+    try {
+        const { VectorDB } = yield Promise.resolve().then(() => __importStar(require("../lib/store/vector-db")));
+        const db = new VectorDB(config_1.PATHS.lancedbDir);
+        const table = yield db.ensureTable();
+        const totalChunks = yield table.countRows();
+        if (totalChunks > 0) {
+            const withSummary = (yield table
+                .query()
+                .where("length(summary) > 5")
+                .select(["id"])
+                .toArray()).length;
+            const pct = Math.round((withSummary / totalChunks) * 100);
+            const symbol = pct >= 90 ? "✅" : pct > 0 ? "⚠️ " : "❌";
+            console.log(`${symbol} Summary coverage: ${withSummary}/${totalChunks} (${pct}%)`);
+        }
+        else {
+            console.log("ℹ️  No indexed chunks yet");
+        }
+        yield db.close();
+    }
+    catch (_b) {
+        console.log("⚠️  Could not check summary coverage");
+    }
     console.log(`\nSystem: ${os.platform()} ${os.arch()} | Node: ${process.version}`);
     console.log("\nIf you see ✅ everywhere, you are ready to search!");
     yield (0, exit_1.gracefulExit)();

package/dist/commands/mcp.js

@@ -585,19 +585,34 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleIndexStatus() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             try {
                 const config = (0, index_config_1.readIndexConfig)(config_1.PATHS.configPath);
                 const projects = (0, project_registry_1.listProjects)();
                 const db = getVectorDb();
                 const stats = yield db.getStats();
                 const fileCount = yield db.getDistinctFileCount();
+                // Watcher status
+                const watcher = (0, watcher_registry_1.getWatcherCoveringPath)(projectRoot);
+                let watcherLine = "Watcher: not running";
+                if (watcher) {
+                    const status = (_a = watcher.status) !== null && _a !== void 0 ? _a : "unknown";
+                    const root = path.basename(watcher.projectRoot);
+                    const reindex = watcher.lastReindex
+                        ? `last reindex: ${Math.round((Date.now() - watcher.lastReindex) / 60000)}m ago`
+                        : "";
+                    watcherLine = `Watcher: ${status} (${root}/)${reindex ? ` ${reindex}` : ""}`;
+                    if (status === "syncing") {
+                        watcherLine += " — search results may be incomplete";
+                    }
+                }
                 const lines = [
                     `Index: ~/.gmax/lancedb (${stats.chunks} chunks, ${fileCount} files)`,
-                    `Model: ${(_a = config === null || config === void 0 ? void 0 : config.embedModel) !== null && _a !== void 0 ? _a : "unknown"} (${(_b = config === null || config === void 0 ? void 0 : config.vectorDim) !== null && _b !== void 0 ? _b : "?"}d, ${(_c = config === null || config === void 0 ? void 0 : config.embedMode) !== null && _c !== void 0 ? _c : "unknown"})`,
+                    `Model: ${(_b = config === null || config === void 0 ? void 0 : config.embedModel) !== null && _b !== void 0 ? _b : "unknown"} (${(_c = config === null || config === void 0 ? void 0 : config.vectorDim) !== null && _c !== void 0 ? _c : "?"}d, ${(_d = config === null || config === void 0 ? void 0 : config.embedMode) !== null && _d !== void 0 ? _d : "unknown"})`,
                     (config === null || config === void 0 ? void 0 : config.indexedAt)
                         ? `Last indexed: ${config.indexedAt}`
                         : "",
+                    watcherLine,
                     "",
                     "Indexed directories:",
                     ...projects.map((p) => { var _a; return `  ${p.name}\t${p.root}\t${(_a = p.lastIndexed) !== null && _a !== void 0 ? _a : "unknown"}`; }),

package/dist/commands/search.js

@@ -122,6 +122,7 @@ function toCompactHits(data) {
                         ? chunk.defined_symbols.toArray().slice(0, 3)
                         : [],
             preview: getPreviewText(chunk),
+            summary: typeof chunk.summary === "string" ? chunk.summary : undefined,
         };
     });
 }
@@ -174,12 +175,12 @@ function padL(s, w) {
     return " ".repeat(n) + s;
 }
 function formatCompactTSV(hits, projectRoot, query) {
-    var _a;
+    var _a, _b;
     if (!hits.length)
         return "No matches found.";
     const lines = [];
     lines.push(`gmax hits\tquery=${query}\tcount=${hits.length}`);
-    lines.push("path\tlines\tscore\trole\tconf\tdefined");
+    lines.push("path\tlines\tscore\trole\tconf\tdefined\tsummary");
     for (const hit of hits) {
         const relPath = path.isAbsolute(hit.path)
             ? path.relative(projectRoot, hit.path)
@@ -188,7 +189,8 @@ function formatCompactTSV(hits, projectRoot, query) {
         const role = compactRole(hit.role);
         const conf = compactConf(hit.confidence);
         const defs = ((_a = hit.defined) !== null && _a !== void 0 ? _a : []).join(",");
-        lines.push([relPath, hit.range, score, role, conf, defs].join("\t"));
+        const summary = (_b = hit.summary) !== null && _b !== void 0 ? _b : "";
+        lines.push([relPath, hit.range, score, role, conf, defs, summary].join("\t"));
     }
     return lines.join("\n");
 }

package/dist/commands/summarize.js

@@ -0,0 +1,83 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarize = void 0;
+const path = __importStar(require("node:path"));
+const commander_1 = require("commander");
+const sync_helpers_1 = require("../lib/index/sync-helpers");
+const syncer_1 = require("../lib/index/syncer");
+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");
+exports.summarize = new commander_1.Command("summarize")
+    .description("Generate LLM summaries for indexed chunks without re-indexing")
+    .option("-p, --path <dir>", "Only summarize chunks under this directory")
+    .action((options) => __awaiter(void 0, void 0, void 0, function* () {
+    const paths = (0, project_root_1.ensureProjectPaths)(process.cwd());
+    const vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
+    const rootPrefix = options.path
+        ? `${path.resolve(options.path)}/`
+        : "";
+    const { spinner } = (0, sync_helpers_1.createIndexingSpinner)("", "Summarizing...");
+    try {
+        const count = yield (0, syncer_1.generateSummaries)(vectorDb, rootPrefix, (done, total) => {
+            spinner.text = `Summarizing... (${done}/${total})`;
+        });
+        if (count > 0) {
+            spinner.succeed(`Summarized ${count} chunks`);
+        }
+        else {
+            spinner.succeed("All chunks already have summaries (or summarizer unavailable)");
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        spinner.fail(`Summarization failed: ${msg}`);
+        process.exitCode = 1;
+    }
+    finally {
+        yield vectorDb.close();
+        yield (0, exit_1.gracefulExit)();
+    }
+}));

package/dist/commands/watch.js

@@ -99,21 +99,31 @@ exports.watch = new commander_1.Command("watch")
     // Propagate project root to worker processes
     process.env.GMAX_PROJECT_ROOT = paths.root;
     console.log(`[watch:${projectName}] Starting...`);
-    // Initial sync if no index
+    // Register early so MCP can see status
+    (0, watcher_registry_1.registerWatcher)({
+        pid: process.pid,
+        projectRoot,
+        startTime: Date.now(),
+        status: "syncing",
+    });
+    // Initial sync if this directory isn't indexed yet
     const vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
-    if (!(yield vectorDb.hasAnyRows())) {
-        console.log(`[watch:${projectName}] No index found, running initial sync...`);
+    const table = yield vectorDb.ensureTable();
+    const prefix = projectRoot.endsWith("/") ? projectRoot : `${projectRoot}/`;
+    const indexed = yield table
+        .query()
+        .select(["id"])
+        .where(`path LIKE '${prefix}%'`)
+        .limit(1)
+        .toArray();
+    if (indexed.length === 0) {
+        console.log(`[watch:${projectName}] No index found for ${projectRoot}, running initial sync...`);
         yield (0, syncer_1.initialSync)({ projectRoot });
         console.log(`[watch:${projectName}] Initial sync complete.`);
     }
+    (0, watcher_registry_1.updateWatcherStatus)(process.pid, "watching");
     // Open resources for watcher
     const metaCache = new meta_cache_1.MetaCache(paths.lmdbPath);
-    // Register
-    (0, watcher_registry_1.registerWatcher)({
-        pid: process.pid,
-        projectRoot,
-        startTime: Date.now(),
-    });
     // Start watching
     const watcher = (0, watcher_1.startWatcher)({
         projectRoot,
@@ -123,6 +133,7 @@ exports.watch = new commander_1.Command("watch")
         onReindex: (files, ms) => {
             console.log(`[watch:${projectName}] Reindexed ${files} file${files !== 1 ? "s" : ""} (${(ms / 1000).toFixed(1)}s)`);
             lastActivity = Date.now();
+            (0, watcher_registry_1.updateWatcherStatus)(process.pid, "watching", Date.now());
         },
     });
     console.log(`[watch:${projectName}] File watcher active`);

package/dist/index.js

@@ -49,6 +49,7 @@ const search_1 = require("./commands/search");
 const serve_1 = require("./commands/serve");
 const setup_1 = require("./commands/setup");
 const skeleton_1 = require("./commands/skeleton");
+const summarize_1 = require("./commands/summarize");
 const symbols_1 = require("./commands/symbols");
 const trace_1 = require("./commands/trace");
 const watch_1 = require("./commands/watch");
@@ -82,5 +83,6 @@ commander_1.program.addCommand(droid_1.installDroid);
 commander_1.program.addCommand(droid_1.uninstallDroid);
 commander_1.program.addCommand(opencode_1.installOpencode);
 commander_1.program.addCommand(opencode_1.uninstallOpencode);
+commander_1.program.addCommand(summarize_1.summarize);
 commander_1.program.addCommand(doctor_1.doctor);
 commander_1.program.parse();

package/dist/lib/index/index-config.js

@@ -51,16 +51,21 @@ const path = __importStar(require("node:path"));
 const config_1 = require("../../config");
 const GLOBAL_CONFIG_PATH = path.join(config_1.PATHS.globalRoot, "config.json");
 function readGlobalConfig() {
+    const defaultEmbedMode = process.arch === "arm64" && process.platform === "darwin" ? "gpu" : "cpu";
     try {
         const raw = fs.readFileSync(GLOBAL_CONFIG_PATH, "utf-8");
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        // Ensure embedMode has a default even if missing from stored config
+        if (!parsed.embedMode)
+            parsed.embedMode = defaultEmbedMode;
+        return parsed;
     }
     catch (_a) {
         const tier = config_1.MODEL_TIERS[config_1.DEFAULT_MODEL_TIER];
         return {
             modelTier: config_1.DEFAULT_MODEL_TIER,
             vectorDim: tier.vectorDim,
-            embedMode: process.arch === "arm64" && process.platform === "darwin" ? "gpu" : "cpu",
+            embedMode: defaultEmbedMode,
         };
     }
 }

package/dist/lib/index/syncer.js

@@ -49,6 +49,7 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
     function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSummaries = generateSummaries;
 exports.initialSync = initialSync;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -62,6 +63,69 @@ const project_root_1 = require("../utils/project-root");
 const pool_1 = require("../workers/pool");
 const index_config_1 = require("./index-config");
 const walker_1 = require("./walker");
+function generateSummaries(db, pathPrefix, onProgress) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let summarizeChunks;
+        try {
+            const mod = yield Promise.resolve().then(() => __importStar(require("../workers/summarize/llm-client")));
+            summarizeChunks = mod.summarizeChunks;
+        }
+        catch (_a) {
+            return 0;
+        }
+        // Quick availability check
+        const test = yield summarizeChunks([
+            { code: "test", language: "ts", file: "test" },
+        ]);
+        if (!test)
+            return 0;
+        const table = yield db.ensureTable();
+        const rows = yield table
+            .query()
+            .select(["id", "path", "content", "defined_symbols"])
+            .where(`path LIKE '${pathPrefix}%' AND (summary IS NULL OR summary = '')`)
+            .limit(50000)
+            .toArray();
+        if (rows.length === 0)
+            return 0;
+        let summarized = 0;
+        const BATCH_SIZE = 5;
+        for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+            const batch = rows.slice(i, i + BATCH_SIZE);
+            const chunks = batch.map((r) => {
+                var _a;
+                const defs = Array.isArray(r.defined_symbols)
+                    ? r.defined_symbols.filter((s) => typeof s === "string")
+                    : typeof ((_a = r.defined_symbols) === null || _a === void 0 ? void 0 : _a.toArray) === "function"
+                        ? r.defined_symbols.toArray()
+                        : [];
+                return {
+                    code: String(r.content || ""),
+                    language: path.extname(String(r.path || "")).replace(/^\./, "") || "unknown",
+                    file: String(r.path || ""),
+                    symbols: defs,
+                };
+            });
+            const summaries = yield summarizeChunks(chunks);
+            if (!summaries)
+                break;
+            const ids = [];
+            const values = [];
+            for (let j = 0; j < batch.length; j++) {
+                if (summaries[j]) {
+                    ids.push(String(batch[j].id));
+                    values.push(summaries[j]);
+                }
+            }
+            if (ids.length > 0) {
+                yield db.updateRows(ids, "summary", values);
+                summarized += ids.length;
+            }
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress(summarized, rows.length);
+        }
+        return summarized;
+    });
+}
 function flushBatch(db, meta, vectors, pendingMeta, pendingDeletes, dryRun) {
     return __awaiter(this, void 0, void 0, function* () {
         if (dryRun)
@@ -388,6 +452,31 @@ function initialSync(options) {
                     metaCache.delete(p);
                 });
             }
+            // --- Summary post-processing (sequential, single process) ---
+            if (!dryRun && indexed > 0) {
+                onProgress === null || onProgress === void 0 ? void 0 : onProgress({
+                    processed,
+                    indexed,
+                    total,
+                    filePath: "Generating summaries...",
+                });
+                const summarized = yield generateSummaries(vectorDb, rootPrefix, (count, chunkTotal) => {
+                    onProgress === null || onProgress === void 0 ? void 0 : onProgress({
+                        processed: count,
+                        indexed,
+                        total: chunkTotal,
+                        filePath: `Summarizing... (${count}/${chunkTotal})`,
+                    });
+                });
+                if (summarized > 0) {
+                    onProgress === null || onProgress === void 0 ? void 0 : onProgress({
+                        processed,
+                        indexed,
+                        total,
+                        filePath: `Summarized ${summarized} chunks`,
+                    });
+                }
+            }
             // Write model config so future runs can detect model changes
             if (!dryRun) {
                 (0, index_config_1.writeIndexConfig)(paths.configPath);

package/dist/lib/index/watcher.js

@@ -50,6 +50,7 @@ const chokidar_1 = require("chokidar");
 const file_utils_1 = require("../utils/file-utils");
 const lock_1 = require("../utils/lock");
 const pool_1 = require("../workers/pool");
+const llm_client_1 = require("../workers/summarize/llm-client");
 // Chokidar ignored — must exclude heavy directories to keep FD count low.
 // On macOS, chokidar uses FSEvents (single FD) but falls back to fs.watch()
 // (one FD per directory) if FSEvents isn't available or for some subdirs.
@@ -103,6 +104,7 @@ function startWatcher(opts) {
         pending.clear();
         const start = Date.now();
         let reindexed = 0;
+        const changedIds = [];
         try {
             const lock = yield (0, lock_1.acquireWriterLockWithRetry)(dataDir, {
                 maxRetries: 3,
@@ -115,10 +117,9 @@ function startWatcher(opts) {
                 const metaUpdates = new Map();
                 const metaDeletes = [];
                 for (const [absPath, event] of batch) {
-                    const relPath = path.relative(projectRoot, absPath);
                     if (event === "unlink") {
-                        deletes.push(relPath);
-                        metaDeletes.push(relPath);
+                        deletes.push(absPath);
+                        metaDeletes.push(absPath);
                         reindexed++;
                         continue;
                     }
@@ -128,9 +129,9 @@ function startWatcher(opts) {
                         if (!(0, file_utils_1.isIndexableFile)(absPath, stats.size))
                             continue;
                         // Check if content actually changed via hash
-                        const cached = metaCache.get(relPath);
+                        const cached = metaCache.get(absPath);
                         const result = yield pool.processFile({
-                            path: relPath,
+                            path: absPath,
                             absolutePath: absPath,
                         });
                         const metaEntry = {
@@ -139,33 +140,36 @@ function startWatcher(opts) {
                             size: result.size,
                         };
                         if (cached && cached.hash === result.hash) {
-                            // Content unchanged (mtime changed but hash same) — just update meta
-                            metaUpdates.set(relPath, metaEntry);
+                            metaUpdates.set(absPath, metaEntry);
                             continue;
                         }
                         if (result.shouldDelete) {
-                            deletes.push(relPath);
-                            metaUpdates.set(relPath, metaEntry);
+                            deletes.push(absPath);
+                            metaUpdates.set(absPath, metaEntry);
                             reindexed++;
                             continue;
                         }
                         // Delete old vectors, insert new
-                        deletes.push(relPath);
+                        deletes.push(absPath);
                         if (result.vectors.length > 0) {
                             vectors.push(...result.vectors);
+                            // Track IDs of new vectors for summarization
+                            for (const v of result.vectors) {
+                                changedIds.push(v.id);
+                            }
                         }
-                        metaUpdates.set(relPath, metaEntry);
+                        metaUpdates.set(absPath, metaEntry);
                         reindexed++;
                     }
                     catch (err) {
                         const code = err === null || err === void 0 ? void 0 : err.code;
                         if (code === "ENOENT") {
-                            deletes.push(relPath);
-                            metaDeletes.push(relPath);
+                            deletes.push(absPath);
+                            metaDeletes.push(absPath);
                             reindexed++;
                         }
                         else {
-                            console.error(`[watch] Failed to process ${relPath}:`, err);
+                            console.error(`[watch] Failed to process ${absPath}:`, err);
                         }
                     }
                 }
@@ -187,6 +191,39 @@ function startWatcher(opts) {
             finally {
                 yield lock.release();
             }
+            // Summarize new/changed chunks outside the lock (sequential, no GPU contention)
+            if (changedIds.length > 0) {
+                try {
+                    const table = yield vectorDb.ensureTable();
+                    for (const id of changedIds) {
+                        const escaped = id.replace(/'/g, "''");
+                        const rows = yield table
+                            .query()
+                            .select(["id", "path", "content"])
+                            .where(`id = '${escaped}'`)
+                            .limit(1)
+                            .toArray();
+                        if (rows.length === 0)
+                            continue;
+                        const r = rows[0];
+                        const lang = path.extname(String(r.path || "")).replace(/^\./, "") ||
+                            "unknown";
+                        const summaries = yield (0, llm_client_1.summarizeChunks)([
+                            {
+                                code: String(r.content || ""),
+                                language: lang,
+                                file: String(r.path || ""),
+                            },
+                        ]);
+                        if (summaries === null || summaries === void 0 ? void 0 : summaries[0]) {
+                            yield vectorDb.updateRows([id], "summary", [summaries[0]]);
+                        }
+                    }
+                }
+                catch (_a) {
+                    // Summarizer unavailable — skip silently
+                }
+            }
             if (reindexed > 0) {
                 const duration = Date.now() - start;
                 onReindex === null || onReindex === void 0 ? void 0 : onReindex(reindexed, duration);

package/dist/lib/store/vector-db.js

@@ -314,6 +314,21 @@ class VectorDB {
             }
         });
     }
+    updateRows(ids, field, values) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!ids.length)
+                return;
+            const table = yield this.ensureTable();
+            for (let i = 0; i < ids.length; i++) {
+                const escaped = ids[i].replace(/'/g, "''");
+                yield table.update({
+                    where: `id = '${escaped}'`,
+                    values: { [field]: (_a = values[i]) !== null && _a !== void 0 ? _a : "" },
+                });
+            }
+        });
+    }
     deletePathsWithPrefix(prefix) {
         return __awaiter(this, void 0, void 0, function* () {
             const table = yield this.ensureTable();

package/dist/lib/utils/watcher-registry.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isProcessRunning = isProcessRunning;
 exports.registerWatcher = registerWatcher;
+exports.updateWatcherStatus = updateWatcherStatus;
 exports.unregisterWatcher = unregisterWatcher;
 exports.getWatcherForProject = getWatcherForProject;
 exports.getWatcherCoveringPath = getWatcherCoveringPath;
@@ -76,6 +77,16 @@ function registerWatcher(info) {
     entries.push(info);
     saveRegistry(entries);
 }
+function updateWatcherStatus(pid, status, lastReindex) {
+    const entries = loadRegistry();
+    const match = entries.find((e) => e.pid === pid);
+    if (match) {
+        match.status = status;
+        if (lastReindex)
+            match.lastReindex = lastReindex;
+        saveRegistry(entries);
+    }
+}
 function unregisterWatcher(pid) {
     const entries = loadRegistry().filter((e) => e.pid !== pid);
     saveRegistry(entries);

package/dist/lib/workers/orchestrator.js

@@ -49,7 +49,6 @@ const transformers_1 = require("@huggingface/transformers");
 const ort = __importStar(require("onnxruntime-node"));
 const uuid_1 = require("uuid");
 const config_1 = require("../../config");
-const llm_client_1 = require("./summarize/llm-client");
 const chunker_1 = require("../index/chunker");
 const skeleton_1 = require("../skeleton");
 const file_utils_1 = require("../utils/file-utils");
@@ -214,23 +213,7 @@ class WorkerOrchestrator {
             if (!chunks.length)
                 return { vectors: [], hash, mtimeMs, size };
             const preparedChunks = this.toPreparedChunks(input.path, hash, chunks, skeletonResult.success ? skeletonResult.skeleton : undefined);
-            // Run embedding and summarization in parallel
-            const lang = path.extname(input.path).replace(/^\./, "") || "unknown";
-            const [hybrids, summaries] = yield Promise.all([
-                this.computeHybrid(preparedChunks.map((chunk) => chunk.content), onProgress),
-                (0, llm_client_1.summarizeChunks)(preparedChunks.map((c) => ({
-                    code: c.content,
-                    language: lang,
-                    file: c.path,
-                }))),
-            ]);
-            // Attach summaries if available
-            if (summaries) {
-                for (let i = 0; i < preparedChunks.length; i++) {
-                    if (summaries[i])
-                        preparedChunks[i].summary = summaries[i];
-                }
-            }
+            const hybrids = yield this.computeHybrid(preparedChunks.map((chunk) => chunk.content), onProgress);
             const vectors = preparedChunks.map((chunk, idx) => {
                 var _a;
                 const hybrid = (_a = hybrids[idx]) !== null && _a !== void 0 ? _a : {

package/dist/lib/workers/summarize/llm-client.js

@@ -3,6 +3,9 @@
  * LLM summarizer HTTP client.
  * Talks to the MLX summarizer server to generate code summaries.
  * Returns null if server isn't running — caller skips summaries gracefully.
+ *
+ * Called from the main syncer process (not worker processes) to avoid
+ * GPU contention from multiple concurrent workers.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -48,14 +51,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.summarizeChunks = summarizeChunks;
-exports.resetSummarizerCache = resetSummarizerCache;
 const http = __importStar(require("node:http"));
 const SUMMARY_PORT = parseInt(process.env.GMAX_SUMMARY_PORT || "8101", 10);
 const SUMMARY_HOST = "127.0.0.1";
-const SUMMARY_TIMEOUT_MS = 120000; // 2 min — batches of chunks take time
-let summarizerAvailable = null;
-let lastCheck = 0;
-const CHECK_INTERVAL_MS = 5000; // short cache — retry quickly if server just started
+const SUMMARY_TIMEOUT_MS = 120000;
 function postJSON(path, body) {
     return new Promise((resolve) => {
         const payload = JSON.stringify(body);
@@ -91,75 +90,18 @@ function postJSON(path, body) {
         req.end();
     });
 }
-function isSummarizerUp() {
-    return __awaiter(this, void 0, void 0, function* () {
-        const now = Date.now();
-        if (summarizerAvailable !== null && now - lastCheck < CHECK_INTERVAL_MS) {
-            return summarizerAvailable;
-        }
-        const result = yield new Promise((resolve) => {
-            const req = http.get({
-                hostname: SUMMARY_HOST,
-                port: SUMMARY_PORT,
-                path: "/health",
-                timeout: 5000,
-            }, (res) => {
-                res.resume();
-                resolve(res.statusCode === 200);
-            });
-            req.on("error", () => resolve(false));
-            req.on("timeout", () => {
-                req.destroy();
-                resolve(false);
-            });
-        });
-        summarizerAvailable = result;
-        lastCheck = now;
-        return result;
-    });
-}
 /**
  * Generate summaries for code chunks via the local LLM server.
- * Sends one chunk at a time. Skips health check — just tries the request.
- * If the server is busy, the TCP connection queues until it's ready.
  * Returns string[] on success, null if server unavailable.
  */
 function summarizeChunks(chunks) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
         if (chunks.length === 0)
             return [];
-        // Quick check only if we've never connected
-        if (summarizerAvailable === null) {
-            summarizerAvailable = yield isSummarizerUp();
-            if (!summarizerAvailable)
-                return null;
-        }
-        if (summarizerAvailable === false) {
-            // Recheck periodically
-            const now = Date.now();
-            if (now - lastCheck < CHECK_INTERVAL_MS)
-                return null;
-            summarizerAvailable = yield isSummarizerUp();
-            if (!summarizerAvailable)
-                return null;
+        const { ok, data } = yield postJSON("/summarize", { chunks });
+        if (!ok || !(data === null || data === void 0 ? void 0 : data.summaries)) {
+            return null;
         }
-        const summaries = [];
-        for (const chunk of chunks) {
-            const { ok, data } = yield postJSON("/summarize", {
-                chunks: [chunk],
-            });
-            if (!ok || !((_a = data === null || data === void 0 ? void 0 : data.summaries) === null || _a === void 0 ? void 0 : _a[0])) {
-                summaries.push("");
-            }
-            else {
-                summaries.push(data.summaries[0]);
-            }
-        }
-        return summaries;
+        return data.summaries;
     });
 }
-function resetSummarizerCache() {
-    summarizerAvailable = null;
-    lastCheck = 0;
-}

package/mlx-embed-server/summarizer.py

@@ -50,8 +50,12 @@ SYSTEM_PROMPT = """You are a code summarizer. Given a code chunk, produce exactl
 Be specific about business logic, services, and side effects. Do not describe syntax.
 Do not use phrases like "This function" or "This code". Start with a verb."""
 
-def build_prompt(code: str, language: str, file: str) -> str:
-    return f"Language: {language}\nFile: {file}\n\n```\n{code}\n```"
+def build_prompt(code: str, language: str, file: str, symbols: list[str] | None = None) -> str:
+    parts = [f"Language: {language}", f"File: {file}"]
+    if symbols:
+        parts.append(f"Defines: {', '.join(symbols)}")
+    parts.append(f"\n```\n{code}\n```")
+    return "\n".join(parts)
 
 
 def is_port_in_use(port: int) -> bool:
@@ -59,11 +63,11 @@ def is_port_in_use(port: int) -> bool:
         return s.connect_ex(("127.0.0.1", port)) == 0
 
 
-def summarize_chunk(code: str, language: str, file: str) -> str:
+def summarize_chunk(code: str, language: str, file: str, symbols: list[str] | None = None) -> str:
     """Generate a one-line summary for a code chunk."""
     messages = [
         {"role": "system", "content": SYSTEM_PROMPT},
-        {"role": "user", "content": build_prompt(code, language, file)},
+        {"role": "user", "content": build_prompt(code, language, file, symbols)},
     ]
     prompt = tokenizer.apply_chat_template(
         messages, tokenize=False, add_generation_prompt=True
@@ -106,6 +110,7 @@ class ChunkInput(BaseModel):
     code: str
     language: str = "unknown"
     file: str = ""
+    symbols: list[str] = []
 
 
 class SummarizeRequest(BaseModel):
@@ -125,7 +130,7 @@ async def summarize(request: SummarizeRequest) -> SummarizeResponse:
     async with _mlx_lock:
         for chunk in request.chunks:
             try:
-                summary = summarize_chunk(chunk.code, chunk.language, chunk.file)
+                summary = summarize_chunk(chunk.code, chunk.language, chunk.file, chunk.symbols or None)
                 summaries.append(summary)
             except Exception as e:
                 summaries.append(f"(summary failed: {e})")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": "Robert Owens <robowens@me.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {
@@ -29,7 +29,7 @@
     "NOTICE"
   ],
   "license": "Apache-2.0",
-  "description": "Local grep-like search tool for your codebase.",
+  "description": "Semantic code search for coding agents. Local embeddings, LLM summaries, call graph tracing.",
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "@huggingface/transformers": "^3.8.0",

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

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

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

@@ -6,63 +6,86 @@ allowed-tools: "mcp__grepmax__semantic_search, mcp__grepmax__search_all, mcp__gr
 
 ## What gmax does
 
-Finds code by meaning. When you'd ask a colleague "where do we handle auth?", use gmax.
+Semantic code search — finds code by meaning, not just strings.
 
-- grep/ripgrep: exact string match, fast
-- gmax: concept match, finds code you couldn't grep for
+- grep/ripgrep: exact string match
+- gmax: concept match ("where do we handle auth?", "how does booking flow work?")
 
 ## MCP tools
 
 ### semantic_search
-Search code by meaning. Returns **pointers** by default — symbol, file:line, role, calls. No code snippets unless requested.
-- `query` (required): Natural language. Be specific — more words = better results.
-- `limit` (optional): Max results (default 3, max 50)
-- `root` (optional): Directory to search. Defaults to project root. Use to search a parent directory (e.g. `root: "../"` to search the monorepo).
-- `path` (optional): Restrict to path prefix (e.g. "src/auth/")
-- `detail` (optional): `"pointer"` (default) or `"code"` (adds 4-line numbered snippets)
-- `min_score` (optional): Filter by minimum relevance score (0-1)
-- `max_per_file` (optional): Cap results per file for diversity
+Search code by meaning. Two output modes:
 
-**Output format (pointer mode):**
+**Pointer mode (default)** — returns metadata + LLM-generated summary per result:
 ```
 handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
+  Validates JWT from Authorization header, checks RBAC permissions, returns 401 on failure
   parent:AuthController calls:validateToken,checkRole,respond
 ```
 
-**When to use `detail: "code"`:** Only when you need to see the actual code before deciding to Read — e.g. comparing implementations, checking syntax. For navigation ("where is X?"), pointer mode is sufficient.
+**Code mode (`detail: "code"`)** — includes 4-line numbered code snippets:
+```
+handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
+  Validates JWT from Authorization header, checks RBAC permissions, returns 401 on failure
+  parent:AuthController calls:validateToken,checkRole,respond
+45│  const token = req.headers.get("Authorization");
+46│  const claims = await validateToken(token);
+47│  if (!claims) return unauthorized();
+48│  const allowed = await checkRole(claims.role, req.path);
+```
+
+Parameters:
+- `query` (required): Natural language. More words = better results.
+- `limit` (optional): Max results (default 3, max 50)
+- `root` (optional): Directory to search. Use `root: "../"` to search a parent directory.
+- `path` (optional): Restrict to path prefix (e.g. "src/auth/")
+- `detail` (optional): `"pointer"` (default) or `"code"`
+- `min_score` (optional): Filter by minimum relevance score (0-1)
+- `max_per_file` (optional): Cap results per file for diversity
+
+**When to use which mode:**
+- `pointer` — navigation, finding locations, understanding architecture
+- `code` — comparing implementations, finding duplicates, checking syntax
 
 ### search_all
-Search ALL indexed code across every directory. Same output format as semantic_search. Use when code could be anywhere — e.g. tracing a function across projects.
+Search ALL indexed code across every directory. Same modes as semantic_search.
 
 ### code_skeleton
-Show file structure — signatures with bodies collapsed (~4x fewer tokens).
+File structure — signatures with bodies collapsed (~4x fewer tokens).
 - `target` (required): File path relative to project root
 
 ### trace_calls
-Trace call graph — who calls a symbol and what it calls. Unscoped — follows calls across all indexed directories.
-- `symbol` (required): Function/method/class name (e.g. "handleAuth")
+Call graph — who calls a symbol and what it calls. Unscoped — follows calls across all indexed directories.
+- `symbol` (required): Function/method/class name
 
 ### list_symbols
 List indexed symbols with definition locations.
-- `pattern` (optional): Filter by name (case-insensitive substring)
-- `limit` (optional): Max results (default 20, max 100)
+- `pattern` (optional): Filter by name
+- `limit` (optional): Max results (default 20)
 - `path` (optional): Only symbols under this path prefix
 
 ### index_status
-Check centralized index health — chunk count, files, indexed directories, model info.
+Check centralized index health — chunks, files, indexed directories, model info.
 
 ## Workflow
 
-1. **Locate** — `semantic_search` with pointer mode to find relevant code
+1. **Search** — `semantic_search` to find relevant code (pointers by default)
 2. **Read** — `Read file:line` for the specific ranges you need
-3. **Trace** — `trace_calls` to understand how functions connect
-4. **Skeleton** — `code_skeleton` before reading large files
+3. **Compare** — `semantic_search` with `detail: "code"` when comparing implementations
+4. **Trace** — `trace_calls` to understand call flow across files
+5. **Skeleton** — `code_skeleton` before reading large files
+
+## If results seem stale
 
-Don't read entire files. Use the line ranges from search results.
+1. Check `index_status` — if watcher shows "syncing", results may be incomplete. Wait for it.
+2. To force a re-index: `Bash(gmax index)` (indexes current directory)
+3. To add summaries without re-indexing: `Bash(gmax summarize)`
+4. Do NOT use `gmax reindex` — it doesn't exist.
 
 ## Tips
 
 - More words = better results. "auth" is vague. "where does the server validate JWT tokens" is specific.
-- ORCH results contain the logic — prioritize these over DEF/IMPL.
+- ORCH results contain the logic — prioritize over DEF/IMPL.
+- Summaries tell you what the code does without reading it. Use them to decide what to Read.
 - Use `root` to search parent directories (monorepo, workspace).
 - Use `search_all` sparingly — it searches everything indexed.