grepmax 0.1.0

package/dist/lib/workers/pool.js

@@ -0,0 +1,373 @@
+"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.WorkerPool = void 0;
+exports.getWorkerPool = getWorkerPool;
+exports.destroyWorkerPool = destroyWorkerPool;
+exports.isWorkerPoolInitialized = isWorkerPoolInitialized;
+/**
+ * Architecture Note: We use a custom Child Process pool instead of Worker Threads
+ * to ensure the ONNX Runtime segfaults do not crash the main process.
+ */
+const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../config");
+function reviveBufferLike(input) {
+    if (input &&
+        typeof input === "object" &&
+        "type" in input &&
+        input.type === "Buffer" &&
+        Array.isArray(input.data)) {
+        return Buffer.from(input.data);
+    }
+    return input;
+}
+function reviveProcessFileResult(result) {
+    if (!result || !Array.isArray(result.vectors))
+        return result;
+    const vectors = result.vectors.map((v) => {
+        const revived = reviveBufferLike(v.colbert);
+        return revived && (Buffer.isBuffer(revived) || revived instanceof Int8Array)
+            ? Object.assign(Object.assign({}, v), { colbert: revived }) : v;
+    });
+    return Object.assign(Object.assign({}, result), { vectors });
+}
+const TASK_TIMEOUT_MS = (() => {
+    var _a;
+    const fromEnv = Number.parseInt((_a = process.env.OSGREP_WORKER_TASK_TIMEOUT_MS) !== null && _a !== void 0 ? _a : "", 10);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    return 120000;
+})();
+const FORCE_KILL_GRACE_MS = 200;
+class ProcessWorker {
+    constructor(modulePath, execArgv) {
+        this.modulePath = modulePath;
+        this.execArgv = execArgv;
+        this.busy = false;
+        this.pendingTaskId = null;
+        this.child = childProcess.fork(modulePath, {
+            execArgv,
+            env: Object.assign({}, process.env),
+        });
+    }
+}
+function resolveProcessWorker() {
+    const jsWorker = path.join(__dirname, "process-child.js");
+    const tsWorker = path.join(__dirname, "process-child.ts");
+    if (fs.existsSync(jsWorker)) {
+        return { filename: jsWorker, execArgv: [] };
+    }
+    if (fs.existsSync(tsWorker)) {
+        return { filename: tsWorker, execArgv: ["-r", "ts-node/register"] };
+    }
+    throw new Error("Process worker file not found");
+}
+class WorkerPool {
+    constructor() {
+        this.workers = [];
+        this.taskQueue = [];
+        this.tasks = new Map();
+        this.nextId = 1;
+        this.destroyed = false;
+        this.destroyPromise = null;
+        const resolved = resolveProcessWorker();
+        this.modulePath = resolved.filename;
+        this.execArgv = resolved.execArgv;
+        const workerCount = Math.max(1, config_1.CONFIG.WORKER_THREADS);
+        for (let i = 0; i < workerCount; i++) {
+            this.spawnWorker();
+        }
+    }
+    clearTaskTimeout(task) {
+        if (task.timeout) {
+            clearTimeout(task.timeout);
+            task.timeout = undefined;
+        }
+    }
+    removeFromQueue(taskId) {
+        const idx = this.taskQueue.indexOf(taskId);
+        if (idx !== -1)
+            this.taskQueue.splice(idx, 1);
+    }
+    completeTask(task, worker) {
+        this.clearTaskTimeout(task);
+        this.tasks.delete(task.id);
+        this.removeFromQueue(task.id);
+        if (worker) {
+            worker.busy = false;
+            worker.pendingTaskId = null;
+        }
+    }
+    handleWorkerExit(worker, code, signal) {
+        worker.busy = false;
+        const failedTasks = Array.from(this.tasks.values()).filter((t) => t.worker === worker);
+        for (const task of failedTasks) {
+            this.clearTaskTimeout(task);
+            task.reject(new Error(`Worker exited unexpectedly${code ? ` (code ${code})` : ""}${signal ? ` signal ${signal}` : ""}`));
+            this.completeTask(task, null);
+        }
+        this.workers = this.workers.filter((w) => w !== worker);
+        if (!this.destroyed) {
+            this.spawnWorker();
+            this.dispatch();
+        }
+    }
+    spawnWorker() {
+        const worker = new ProcessWorker(this.modulePath, this.execArgv);
+        const onMessage = (msg) => {
+            const task = this.tasks.get(msg.id);
+            if (!task)
+                return;
+            if ("heartbeat" in msg) {
+                // Reset timeout
+                this.clearTaskTimeout(task);
+                if (task.worker) {
+                    task.timeout = setTimeout(() => this.handleTaskTimeout(task, task.worker), TASK_TIMEOUT_MS);
+                }
+                return;
+            }
+            if ("error" in msg) {
+                task.reject(new Error(msg.error));
+            }
+            else {
+                let result = msg.result;
+                if (task.method === "processFile") {
+                    result = reviveProcessFileResult(result);
+                }
+                task.resolve(result);
+            }
+            this.completeTask(task, worker);
+            this.dispatch();
+        };
+        const onExit = (code, signal) => this.handleWorkerExit(worker, code, signal);
+        worker.child.on("message", onMessage);
+        worker.child.on("exit", onExit);
+        this.workers.push(worker);
+    }
+    enqueue(method, payload, signal) {
+        if (this.destroyed) {
+            return Promise.reject(new Error("Worker pool destroyed"));
+        }
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            const err = new Error("Aborted");
+            err.name = "AbortError";
+            return Promise.reject(err);
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const safeResolve = (val) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(val);
+                }
+            };
+            const safeReject = (reason) => {
+                if (!settled) {
+                    settled = true;
+                    reject(reason);
+                }
+            };
+            const task = {
+                id,
+                method,
+                payload,
+                resolve: safeResolve,
+                reject: safeReject,
+            };
+            if (signal) {
+                signal.addEventListener("abort", () => {
+                    // If task is still in queue, remove it
+                    const idx = this.taskQueue.indexOf(id);
+                    if (idx !== -1) {
+                        this.taskQueue.splice(idx, 1);
+                        this.tasks.delete(id);
+                        const err = new Error("Aborted");
+                        err.name = "AbortError";
+                        safeReject(err);
+                    }
+                    // If task is already running (assigned to worker), we can't easily kill it without
+                    // killing the worker. For now, we just let it finish but reject the promise early so
+                    // the caller doesn't wait. The worker will eventually finish and we'll ignore the result.
+                    else if (this.tasks.has(id)) {
+                        // Task is running. Reject caller immediately.
+                        const err = new Error("Aborted");
+                        err.name = "AbortError";
+                        safeReject(err);
+                        // We intentionally do NOT delete the task map entry here,
+                        // because we need handleWorkerMessage to cleanly cleanup the worker state
+                        // when it eventually finishes.
+                    }
+                }, { once: true });
+            }
+            this.tasks.set(id, task);
+            this.taskQueue.push(id);
+            this.dispatch();
+        });
+    }
+    handleTaskTimeout(task, worker) {
+        if (this.destroyed || !this.tasks.has(task.id))
+            return;
+        this.clearTaskTimeout(task);
+        if (task.method !== "processFile") {
+            console.warn(`[worker-pool] ${task.method} timed out after ${TASK_TIMEOUT_MS}ms; restarting worker.`);
+        }
+        this.completeTask(task, null);
+        task.reject(new Error(`Worker task ${task.method} timed out after ${TASK_TIMEOUT_MS}ms`));
+        worker.child.removeAllListeners("message");
+        worker.child.removeAllListeners("exit");
+        try {
+            worker.child.kill("SIGKILL");
+        }
+        catch (_a) { }
+        this.workers = this.workers.filter((w) => w !== worker);
+        if (!this.destroyed) {
+            this.spawnWorker();
+        }
+        this.dispatch();
+    }
+    dispatch() {
+        if (this.destroyed)
+            return;
+        const idle = this.workers.find((w) => !w.busy);
+        const nextTaskId = this.taskQueue.find((id) => {
+            const t = this.tasks.get(id);
+            return t && !t.worker;
+        });
+        if (!idle || nextTaskId === undefined)
+            return;
+        const task = this.tasks.get(nextTaskId);
+        if (!task) {
+            this.removeFromQueue(nextTaskId);
+            this.dispatch();
+            return;
+        }
+        idle.busy = true;
+        idle.pendingTaskId = task.id;
+        task.worker = idle;
+        task.timeout = setTimeout(() => this.handleTaskTimeout(task, idle), TASK_TIMEOUT_MS);
+        try {
+            idle.child.send({
+                id: task.id,
+                method: task.method,
+                payload: task.payload,
+            });
+        }
+        catch (err) {
+            this.clearTaskTimeout(task);
+            this.completeTask(task, idle);
+            task.reject(err);
+            return;
+        }
+        this.dispatch();
+    }
+    processFile(input) {
+        // ProcessFile doesn't currently use cancellation, but we could add it later
+        return this.enqueue("processFile", input);
+    }
+    encodeQuery(text, signal) {
+        return this.enqueue("encodeQuery", { text }, signal);
+    }
+    rerank(input, signal) {
+        return this.enqueue("rerank", input, signal);
+    }
+    destroy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.destroyPromise)
+                return this.destroyPromise;
+            if (this.destroyed)
+                return;
+            this.destroyed = true;
+            for (const task of this.tasks.values()) {
+                this.clearTaskTimeout(task);
+                task.reject(new Error("Worker pool destroyed"));
+            }
+            this.tasks.clear();
+            this.taskQueue = [];
+            const killPromises = this.workers.map((w) => new Promise((resolve) => {
+                w.child.removeAllListeners("message");
+                w.child.removeAllListeners("exit");
+                w.child.once("exit", () => resolve());
+                w.child.kill("SIGTERM");
+                const force = setTimeout(() => {
+                    try {
+                        w.child.kill("SIGKILL");
+                    }
+                    catch (_a) { }
+                }, FORCE_KILL_GRACE_MS);
+                setTimeout(() => {
+                    clearTimeout(force);
+                    resolve();
+                }, config_1.WORKER_TIMEOUT_MS);
+            }));
+            this.destroyPromise = Promise.allSettled(killPromises).then(() => {
+                this.workers = [];
+                this.destroyPromise = null;
+            });
+            yield this.destroyPromise;
+        });
+    }
+}
+exports.WorkerPool = WorkerPool;
+let singleton = null;
+function getWorkerPool() {
+    if (!singleton) {
+        singleton = new WorkerPool();
+    }
+    return singleton;
+}
+function destroyWorkerPool() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!singleton)
+            return;
+        const pool = singleton;
+        singleton = null;
+        yield pool.destroy();
+    });
+}
+function isWorkerPoolInitialized() {
+    return singleton !== null;
+}

package/dist/lib/workers/process-child.js

@@ -0,0 +1,92 @@
+"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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_process_1 = __importDefault(require("node:process"));
+const worker_1 = __importStar(require("./worker"));
+const send = (msg) => {
+    if (node_process_1.default.send) {
+        node_process_1.default.send(msg);
+    }
+};
+node_process_1.default.on("message", (msg) => __awaiter(void 0, void 0, void 0, function* () {
+    const { id, method, payload } = msg;
+    try {
+        if (method === "processFile") {
+            const onProgress = () => {
+                send({ id, heartbeat: true });
+            };
+            const result = yield (0, worker_1.default)(payload, onProgress);
+            send({ id, result });
+            return;
+        }
+        if (method === "encodeQuery") {
+            const result = yield (0, worker_1.encodeQuery)(payload);
+            send({ id, result });
+            return;
+        }
+        if (method === "rerank") {
+            const result = yield (0, worker_1.rerank)(payload);
+            send({ id, result });
+            return;
+        }
+        send({ id, error: `Unknown method: ${method}` });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        send({ id, error: message });
+    }
+}));
+node_process_1.default.on("uncaughtException", (err) => {
+    console.error("[process-worker] uncaughtException", err);
+    node_process_1.default.exitCode = 1;
+    node_process_1.default.exit();
+});
+node_process_1.default.on("unhandledRejection", (reason) => {
+    console.error("[process-worker] unhandledRejection", reason);
+    node_process_1.default.exitCode = 1;
+    node_process_1.default.exit();
+});

package/dist/lib/workers/worker.js

@@ -0,0 +1,31 @@
+"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.default = processFile;
+exports.encodeQuery = encodeQuery;
+exports.rerank = rerank;
+const orchestrator_1 = require("./orchestrator");
+const orchestrator = new orchestrator_1.WorkerOrchestrator();
+function processFile(input, onProgress) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return orchestrator.processFile(input, onProgress);
+    });
+}
+function encodeQuery(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return orchestrator.encodeQuery(input.text);
+    });
+}
+function rerank(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return orchestrator.rerank(input);
+    });
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "grepmax",
+  "version": "0.1.0",
+  "author": "Robert Owens <robowens@me.com>",
+  "homepage": "https://github.com/reowens/grepmax",
+  "bugs": {
+    "url": "https://github.com/reowens/grepmax/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reowens/grepmax.git"
+  },
+  "main": "index.js",
+  "bin": {
+    "osgrep": "dist/index.js"
+  },
+  "scripts": {
+    "prebuild": "mkdir -p dist",
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "dev": "npx tsc && node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "benchmark": "./run-benchmark.sh",
+    "benchmark:index": "./run-benchmark.sh $HOME/osgrep-benchmarks --index",
+    "benchmark:agent": "npx tsx src/bench/benchmark-agent.ts",
+    "benchmark:chart": "npx tsx src/bench/generate-benchmark-chart.ts",
+    "format": "biome check --write .",
+    "format:check": "biome check .",
+    "lint": "biome lint .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "osgrep",
+    "grep",
+    "glob",
+    "search"
+  ],
+  "files": [
+    "dist",
+    "plugins",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "license": "Apache-2.0",
+  "description": "Local grep-like search tool for your codebase.",
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@huggingface/transformers": "^3.8.0",
+    "@lancedb/lancedb": "^0.26.2",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "apache-arrow": "^18.1.0",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "cli-highlight": "^2.1.11",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "lmdb": "^3.4.4",
+    "onnxruntime-node": "1.24.3",
+    "ora": "^5.4.1",
+    "piscina": "^5.1.4",
+    "simsimd": "^6.5.5",
+    "uuid": "^13.0.0",
+    "web-tree-sitter": "^0.26.6",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.76",
+    "@biomejs/biome": "2.4.7",
+    "@types/node": "^25.5.0",
+    "node-gyp": "^12.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "name": "osgrep",
+  "version": "0.1.0",
+  "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
+  "author": {
+    "name": "Robert Owens",
+    "email": "robowens@me.com"
+  },
+  "hooks": "./hooks.json",
+  "homepage": "https://github.com/reowens/osgrep-max",
+  "repository": "https://github.com/reowens/osgrep-max",
+  "license": "Apache-2.0",
+  "keywords": [
+    "search",
+    "semantic",
+    "grep",
+    "code-search",
+    "semantic-search"
+  ]
+}

package/plugins/osgrep/hooks/start.js

@@ -0,0 +1,90 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const _path = require("node:path");
+const http = require("node:http");
+const { spawn } = require("node:child_process");
+
+function readPayload() {
+  try {
+    const raw = fs.readFileSync(0, "utf-8");
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function isServerRunning(cwd) {
+  // Read the global server registry (matches how osgrep serve registers)
+  const registryPath = _path.join(os.homedir(), ".osgrep", "servers.json");
+  try {
+    const servers = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
+    const match = servers.find((s) => s.projectRoot === cwd);
+    if (match && typeof match.pid === "number") {
+      process.kill(match.pid, 0); // throws if not running
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
+function isMlxRunning() {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { hostname: "127.0.0.1", port: 8100, path: "/health", timeout: 1000 },
+      (res) => {
+        res.resume();
+        resolve(res.statusCode === 200);
+      }
+    );
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+function startMlxServer() {
+  // Find the mlx-embed-server directory relative to plugin root
+  const pluginRoot = __dirname.replace(/\/hooks$/, "");
+  const osgrepRoot = _path.resolve(pluginRoot, "../..");
+  const serverDir = _path.join(osgrepRoot, "mlx-embed-server");
+
+  if (!fs.existsSync(_path.join(serverDir, "server.py"))) return;
+
+  const logPath = "/tmp/mlx-embed-server.log";
+  const out = fs.openSync(logPath, "a");
+
+  const child = spawn("uv", ["run", "python", "server.py"], {
+    cwd: serverDir,
+    detached: true,
+    stdio: ["ignore", out, out],
+  });
+  child.unref();
+}
+
+async function main() {
+  const payload = readPayload();
+  const cwd = payload.cwd || process.cwd();
+
+  // Check if osgrep serve is running (read-only — MCP server owns daemon lifecycle)
+  const daemonUp = isServerRunning(cwd);
+
+  // Start MLX embed server if not running (set OSGREP_EMBED_MODE=cpu to skip)
+  const embedMode = process.env.OSGREP_EMBED_MODE || "auto";
+  if (embedMode !== "cpu") {
+    const mlxUp = await isMlxRunning();
+    if (!mlxUp) {
+      startMlxServer();
+    }
+  }
+
+  const status = daemonUp ? "running" : "starting via MCP";
+  const response = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext:
+        `osgrep serve ${status}; prefer \`osgrep "<complete question>"\` over grep (plain output is agent-friendly).`,
+    },
+  };
+  process.stdout.write(JSON.stringify(response));
+}
+
+main();

package/plugins/osgrep/hooks/stop.js

@@ -0,0 +1,3 @@
+// No-op: let osgrep serve persist across sessions.
+// The start hook ensures exactly one is running.
+// Use `osgrep serve stop` to explicitly shut it down.