grepmax 0.6.5 → 0.7.2

package/README.md

@@ -106,6 +106,7 @@ In our public benchmarks, `grepmax` can save about 20% of your LLM tokens and de
 | `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 |
+| `summarize_directory` | Generate LLM summaries for indexed chunks. Summaries appear in search results. |
 
 ## Commands
 
@@ -193,6 +194,17 @@ gmax skeleton "auth logic"        # Search, skeletonize top matches
 
 **Supported Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP, Swift, Kotlin.
 
+### `gmax config`
+
+View or update configuration without the full interactive setup.
+
+```bash
+gmax config                          # Show current settings
+gmax config --embed-mode cpu         # Switch to CPU embeddings
+gmax config --embed-mode gpu         # Switch to GPU (MLX)
+gmax config --model-tier standard    # Switch to standard model (768d)
+```
+
 ### `gmax doctor`
 
 Checks installation health, model paths, and database integrity.
@@ -244,9 +256,31 @@ handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
 
 ## Configuration
 
+### Config File
+
+Settings are stored in `~/.gmax/config.json`:
+
+```json
+{
+  "modelTier": "small",
+  "vectorDim": 384,
+  "embedMode": "gpu",
+  "mlxModel": "ibm-granite/granite-embedding-small-english-r2"
+}
+```
+
+View and change settings with `gmax config` or run `gmax setup` for interactive configuration.
+
 ### Ignoring Files
 
-gmax respects `.gitignore` and `.gmaxignore` files. Create a `.gmaxignore` in your directory root to exclude additional patterns.
+gmax respects `.gitignore` and `.gmaxignore` files. Create a `.gmaxignore` in your directory root to exclude additional patterns:
+
+```gitignore
+# .gmaxignore — same syntax as .gitignore
+docs/generated/
+*.test.ts
+fixtures/
+```
 
 ### Index Management
 
@@ -255,15 +289,21 @@ gmax respects `.gitignore` and `.gmaxignore` files. Create a `.gmaxignore` in yo
 - **Clean up:** `gmax index --reset` re-indexes the current directory from scratch
 - **Full reset:** `rm -rf ~/.gmax/lancedb ~/.gmax/cache` to start completely fresh
 
-## Development
+### Environment Variables
 
-```bash
-pnpm install
-pnpm build
-pnpm test         # vitest
-pnpm format       # biome check
-just deploy       # publish latest tag to npm
-```
+| Variable | Description | Default |
+| --- | --- | --- |
+| `GMAX_WORKER_THREADS` | Number of worker threads for embedding | 50% of CPU cores |
+| `GMAX_EMBED_MODE` | Force `cpu` or `gpu` embedding mode | Auto-detect |
+| `GMAX_DEBUG` | Enable debug logging (`1` to enable) | Off |
+| `GMAX_VERBOSE` | Enable verbose output (`1` to enable) | Off |
+| `GMAX_WORKER_TASK_TIMEOUT_MS` | Worker task timeout in ms | `120000` |
+| `GMAX_MAX_WORKER_MEMORY_MB` | Max worker memory in MB | 50% of system RAM |
+| `GMAX_MAX_PER_FILE` | Default max results per file in search | `3` |
+
+## Contributing
+
+See [CLAUDE.md](CLAUDE.md) for development setup, commands, and architecture details.
 
 ## Troubleshooting
 

package/dist/commands/config.js

@@ -0,0 +1,80 @@
+"use strict";
+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.config = void 0;
+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.config = new commander_1.Command("config")
+    .description("View or update gmax configuration")
+    .option("--embed-mode <mode>", "Set embedding mode: cpu or gpu")
+    .option("--model-tier <tier>", "Set model tier: small (384d) or standard (768d)")
+    .addHelpText("after", `
+Examples:
+  gmax config                          Show current configuration
+  gmax config --embed-mode cpu         Switch to CPU embeddings
+  gmax config --model-tier standard    Switch to standard model (768d)
+`)
+    .action((_opts, cmd) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b, _c, _d;
+    const options = cmd.optsWithGlobals();
+    const globalConfig = (0, index_config_1.readGlobalConfig)();
+    const paths = (0, project_root_1.ensureProjectPaths)(process.cwd());
+    const indexConfig = (0, index_config_1.readIndexConfig)(paths.configPath);
+    const hasUpdates = options.embedMode !== undefined || options.modelTier !== undefined;
+    if (!hasUpdates) {
+        // Show current config
+        const tier = (_a = config_1.MODEL_TIERS[globalConfig.modelTier]) !== null && _a !== void 0 ? _a : config_1.MODEL_TIERS.small;
+        console.log("gmax configuration (~/.gmax/config.json)\n");
+        console.log(`  Model tier:  ${globalConfig.modelTier} (${tier.vectorDim}d, ${tier.params})`);
+        console.log(`  Embed mode:  ${globalConfig.embedMode}`);
+        console.log(`  Embed model: ${globalConfig.embedMode === "gpu" ? tier.mlxModel : tier.onnxModel}`);
+        if (indexConfig === null || indexConfig === void 0 ? void 0 : indexConfig.indexedAt) {
+            console.log(`  Last indexed: ${indexConfig.indexedAt}`);
+        }
+        console.log(`\nTo change: gmax config --embed-mode <cpu|gpu> --model-tier <small|standard>`);
+        yield (0, exit_1.gracefulExit)();
+        return;
+    }
+    // Validate inputs
+    if (options.embedMode && !["cpu", "gpu"].includes(options.embedMode)) {
+        console.error(`Invalid embed mode: ${options.embedMode} (use cpu or gpu)`);
+        yield (0, exit_1.gracefulExit)(1);
+        return;
+    }
+    if (options.modelTier && !config_1.MODEL_TIERS[options.modelTier]) {
+        console.error(`Invalid model tier: ${options.modelTier} (use ${Object.keys(config_1.MODEL_TIERS).join(" or ")})`);
+        yield (0, exit_1.gracefulExit)(1);
+        return;
+    }
+    const newTier = (_b = options.modelTier) !== null && _b !== void 0 ? _b : globalConfig.modelTier;
+    const newMode = (_c = options.embedMode) !== null && _c !== void 0 ? _c : globalConfig.embedMode;
+    const tier = (_d = config_1.MODEL_TIERS[newTier]) !== null && _d !== void 0 ? _d : config_1.MODEL_TIERS.small;
+    const tierChanged = newTier !== globalConfig.modelTier;
+    (0, index_config_1.writeGlobalConfig)({
+        modelTier: newTier,
+        vectorDim: tier.vectorDim,
+        embedMode: newMode,
+        mlxModel: newMode === "gpu" ? tier.mlxModel : undefined,
+    });
+    (0, index_config_1.writeSetupConfig)(paths.configPath, {
+        embedMode: newMode,
+        mlxModel: newMode === "gpu" ? tier.mlxModel : undefined,
+        modelTier: newTier,
+    });
+    console.log(`Updated: embed-mode=${newMode}, model-tier=${newTier} (${tier.vectorDim}d)`);
+    if (tierChanged) {
+        console.log("⚠️  Model tier changed — run `gmax index --reset` to rebuild with new dimensions.");
+    }
+    yield (0, exit_1.gracefulExit)();
+}));

package/dist/commands/doctor.js

@@ -52,7 +52,7 @@ 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")
+    .description("Check installation health, models, and index status")
     .action(() => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     console.log("🏥 gmax Doctor\n");

package/dist/commands/index.js

@@ -60,6 +60,13 @@ exports.index = new commander_1.Command("index")
     .option("-p, --path <dir>", "Path to index (defaults to current directory)", "")
     .option("-r, --reset", "Remove existing index and re-index from scratch", false)
     .option("-v, --verbose", "Show detailed progress with file names", false)
+    .addHelpText("after", `
+Examples:
+  gmax index                     Index current directory
+  gmax index --path ~/workspace  Index a specific directory
+  gmax index --dry-run           Preview what would be indexed
+  gmax index --reset             Full re-index from scratch
+`)
     .action((_args, cmd) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const options = cmd.optsWithGlobals();

package/dist/commands/mcp.js

@@ -239,13 +239,15 @@ function err(text) {
 // Command
 // ---------------------------------------------------------------------------
 exports.mcp = new commander_1.Command("mcp")
-    .description("Start MCP server for gmax")
+    .description("Start MCP server (stdio, auto-started by plugins)")
     .action((_optsArg, _cmd) => __awaiter(void 0, void 0, void 0, function* () {
     // --- Lifecycle ---
     let _vectorDb = null;
     let _searcher = null;
     let _skeletonizer = null;
     let _indexReady = false;
+    let _indexing = false;
+    let _indexProgress = "";
     const cleanup = () => __awaiter(void 0, void 0, void 0, function* () {
         if (_vectorDb) {
             try {
@@ -310,14 +312,33 @@ exports.mcp = new commander_1.Command("mcp")
                 const db = getVectorDb();
                 const hasIndex = yield db.hasRowsForPath(projectRoot);
                 if (!hasIndex) {
+                    if (_indexing)
+                        return; // Already indexing in background
+                    _indexing = true;
+                    _indexProgress = "starting...";
                     console.log("[MCP] No index found, running initial sync...");
-                    yield (0, syncer_1.initialSync)({ projectRoot });
-                    console.log("[MCP] Initial sync complete.");
+                    (0, syncer_1.initialSync)({
+                        projectRoot,
+                        onProgress: (info) => {
+                            _indexProgress = `${info.processed}/${info.total || "?"} files`;
+                        },
+                    })
+                        .then(() => {
+                        _indexReady = true;
+                        _indexing = false;
+                        _indexProgress = "";
+                        console.log("[MCP] Initial sync complete.");
+                    })
+                        .catch((e) => {
+                        _indexing = false;
+                        _indexProgress = "";
+                        console.error("[MCP] Index sync failed:", e);
+                    });
                 }
                 else {
                     console.log("[MCP] Index exists, ready.");
+                    _indexReady = true;
                 }
-                _indexReady = true;
             }
             catch (e) {
                 console.error("[MCP] Index sync failed:", e);
@@ -345,6 +366,9 @@ exports.mcp = new commander_1.Command("mcp")
             const limit = Math.min(Math.max(Number(args.limit) || 3, 1), 50);
             yield ensureIndexReady();
             ensureWatcher();
+            if (_indexing) {
+                return ok(`Indexing in progress (${_indexProgress}). Results may be incomplete or empty — try again shortly.`);
+            }
             try {
                 const searcher = getSearcher();
                 // Determine path prefix and display root for relative paths
@@ -492,6 +516,9 @@ exports.mcp = new commander_1.Command("mcp")
             const symbol = String(args.symbol || "");
             if (!symbol)
                 return err("Missing required parameter: symbol");
+            if (_indexing) {
+                return ok(`Indexing in progress (${_indexProgress}). trace_calls requires a complete index — try again shortly.`);
+            }
             try {
                 const db = getVectorDb();
                 const builder = new graph_builder_1.GraphBuilder(db);
@@ -534,6 +561,9 @@ exports.mcp = new commander_1.Command("mcp")
             const pattern = typeof args.pattern === "string" ? args.pattern : undefined;
             const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 100);
             const pathPrefix = typeof args.path === "string" ? args.path : undefined;
+            if (_indexing) {
+                return ok(`Indexing in progress (${_indexProgress}). list_symbols requires a complete index — try again shortly.`);
+            }
             try {
                 const db = getVectorDb();
                 const table = yield db.ensureTable();
@@ -621,6 +651,9 @@ exports.mcp = new commander_1.Command("mcp")
                         watcherLine += " — search results may be incomplete";
                     }
                 }
+                const indexingLine = _indexing
+                    ? `Indexing: in progress (${_indexProgress})`
+                    : "";
                 const lines = [
                     `Index: ~/.gmax/lancedb (${stats.chunks} chunks, ${fileCount} files)`,
                     `Model: ${globalConfig.embedMode === "gpu" ? ((_d = (_c = (_b = config_1.MODEL_TIERS[globalConfig.modelTier]) === null || _b === void 0 ? void 0 : _b.mlxModel) !== null && _c !== void 0 ? _c : config === null || config === void 0 ? void 0 : config.embedModel) !== null && _d !== void 0 ? _d : "unknown") : ((_e = config === null || config === void 0 ? void 0 : config.embedModel) !== null && _e !== void 0 ? _e : "unknown")} (${(_f = config === null || config === void 0 ? void 0 : config.vectorDim) !== null && _f !== void 0 ? _f : "?"}d, ${globalConfig.embedMode})`,
@@ -628,6 +661,7 @@ exports.mcp = new commander_1.Command("mcp")
                         ? `Last indexed: ${config.indexedAt}`
                         : "",
                     watcherLine,
+                    indexingLine,
                     "",
                     "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

@@ -325,7 +325,7 @@ function outputSkeletons(results, projectRoot, limit, db) {
     });
 }
 exports.search = new commander_1.Command("search")
-    .description("File pattern searcher")
+    .description("Search code by meaning (default command)")
     .option("-m <max_count>, --max-count <max_count>", "The maximum number of results to return (total)", "5")
     .option("-c, --content", "Show full chunk content instead of snippets", false)
     .option("--per-file <n>", "Number of matches to show per file", "3")
@@ -336,8 +336,15 @@ exports.search = new commander_1.Command("search")
     .option("-s, --sync", "Syncs the local files to the store before searching", false)
     .option("-d, --dry-run", "Show what would be indexed without actually indexing", false)
     .option("--skeleton", "Show code skeleton for matching files instead of snippets", false)
-    .argument("<pattern>", "The pattern to search for")
-    .argument("[path]", "The path to search in")
+    .argument("<pattern>", "Natural language query (e.g. \"where do we handle auth?\")")
+    .argument("[path]", "Restrict search to this path prefix")
+    .addHelpText("after", `
+Examples:
+  gmax "where do we handle authentication?"
+  gmax "database connection pooling" -m 10
+  gmax "error handling" --compact --min-score 0.5
+  gmax "validation logic" --skeleton
+`)
     .action((pattern, exec_path, _options, cmd) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
     const options = cmd.optsWithGlobals();

package/dist/commands/serve.js

@@ -100,7 +100,7 @@ function startMlxServer(mlxModel) {
     return child;
 }
 exports.serve = new commander_1.Command("serve")
-    .description("Run gmax as a background server with live indexing")
+    .description("HTTP search server with live file watching")
     .option("-p, --port <port>", "Port to listen on", process.env.GMAX_PORT || "4444")
     .option("-b, --background", "Run in background", false)
     .option("--cpu", "Use CPU-only embeddings (skip MLX GPU server)", false)

package/dist/commands/skeleton.js

@@ -112,6 +112,12 @@ exports.skeleton = new commander_1.Command("skeleton")
     .option("--json", "Output as JSON", false)
     .option("--no-summary", "Omit call/complexity summary in bodies", false)
     .option("-s, --sync", "Sync index before searching", false)
+    .addHelpText("after", `
+Examples:
+  gmax skeleton src/lib/auth.ts  Show file structure
+  gmax skeleton AuthService      Find symbol, show its file
+  gmax skeleton "auth logic"     Search, skeletonize top matches
+`)
     .action((target, options, _cmd) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b;
     let vectorDb = null;

package/dist/index.js

@@ -39,6 +39,7 @@ const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const claude_code_1 = require("./commands/claude-code");
 const codex_1 = require("./commands/codex");
+const config_1 = require("./commands/config");
 const doctor_1 = require("./commands/doctor");
 const droid_1 = require("./commands/droid");
 const index_1 = require("./commands/index");
@@ -54,6 +55,8 @@ const symbols_1 = require("./commands/symbols");
 const trace_1 = require("./commands/trace");
 const watch_1 = require("./commands/watch");
 commander_1.program
+    .name("gmax")
+    .description("Semantic code search — finds code by meaning, not just strings")
     .version(JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), {
     encoding: "utf-8",
 })).version)
@@ -67,22 +70,29 @@ if (legacyProjectData) {
     console.log("   gmax now uses a centralized index at ~/.gmax/lancedb/.");
     console.log("   Run 'gmax index' to re-index into the centralized store.");
 }
+// Core commands
 commander_1.program.addCommand(search_1.search, { isDefault: true });
 commander_1.program.addCommand(index_1.index);
 commander_1.program.addCommand(list_1.list);
 commander_1.program.addCommand(skeleton_1.skeleton);
 commander_1.program.addCommand(symbols_1.symbols);
 commander_1.program.addCommand(trace_1.trace);
-commander_1.program.addCommand(setup_1.setup);
+// Services
 commander_1.program.addCommand(serve_1.serve);
 commander_1.program.addCommand(watch_1.watch);
 commander_1.program.addCommand(mcp_1.mcp);
+commander_1.program.addCommand(summarize_1.summarize);
+// Setup & diagnostics
+commander_1.program.addCommand(setup_1.setup);
+commander_1.program.addCommand(config_1.config);
+commander_1.program.addCommand(doctor_1.doctor);
+// Plugin installers
 commander_1.program.addCommand(claude_code_1.installClaudeCode);
 commander_1.program.addCommand(codex_1.installCodex);
 commander_1.program.addCommand(droid_1.installDroid);
+droid_1.uninstallDroid._hidden = true;
 commander_1.program.addCommand(droid_1.uninstallDroid);
 commander_1.program.addCommand(opencode_1.installOpencode);
+opencode_1.uninstallOpencode._hidden = true;
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.6.5",
+  "version": "0.7.2",
   "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.6.5",
+  "version": "0.7.2",
   "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

@@ -35,10 +35,10 @@ handleAuth [exported ORCH C:8] src/auth/handler.ts:45-90
 ```
 
 Parameters:
-- `query` (required): Natural language. More words = better results.
+- `query` (required): Natural language. Be specific — 5+ words gives much better results than 1-2 words.
 - `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/")
+- `root` (optional): Absolute path to search a different indexed directory.
+- `path` (optional): Restrict to path prefix (e.g. "src/auth/"). Relative to the search root.
 - `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
@@ -48,7 +48,9 @@ Parameters:
 - `code` — comparing implementations, finding duplicates, checking syntax
 
 ### search_all
-Search ALL indexed code across every directory. Same modes as semantic_search.
+Search ALL indexed code across every directory. Same parameters as semantic_search (query, limit, detail, min_score, max_per_file) but without `root` or `path` — searches everything.
+
+Use sparingly. Prefer `semantic_search` when you know which directory to search.
 
 ### code_skeleton
 File structure — signatures with bodies collapsed (~4x fewer tokens).
@@ -60,16 +62,17 @@ Call graph — who calls a symbol and what it calls. Unscoped — follows calls
 
 ### list_symbols
 List indexed symbols with definition locations.
-- `pattern` (optional): Filter by name
-- `limit` (optional): Max results (default 20)
+- `pattern` (optional): Filter by name (case-insensitive substring match)
+- `limit` (optional): Max results (default 20, max 100)
 - `path` (optional): Only symbols under this path prefix
 
 ### index_status
-Check centralized index health — chunks, files, indexed directories, model info.
+Check centralized index health — chunks, files, indexed directories, model info, watcher status.
 
 ### summarize_directory
-Generate LLM summaries for indexed code in a directory. Summaries are stored and returned in search results. Run after indexing a new directory.
+Generate LLM summaries for indexed code in a directory. Summaries are stored and returned in search results. Requires the summarizer server (auto-started by the plugin hook).
 - `path` (optional): Directory to summarize. Defaults to project root.
+- `limit` (optional): Max chunks to summarize per call (default 200, max 5000). Run again to continue.
 
 ## Workflow
 
@@ -81,15 +84,22 @@ Generate LLM summaries for indexed code in a directory. Summaries are stored and
 
 ## If results seem stale
 
-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)
+The watcher auto-starts when the MCP server connects — it detects file changes and re-indexes in the background. Usually results are fresh without manual intervention.
+
+1. Check `index_status` — if watcher shows "syncing", wait for it to finish.
+2. To force a full 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.
 
+## Search warnings
+
+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.
+
 ## Tips
 
-- More words = better results. "auth" is vague. "where does the server validate JWT tokens" is specific.
-- 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.
+- **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.
+- **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.
+- **Don't search for exact strings** — use grep/Grep for that. gmax finds concepts, not literals.