@meyverick/omnicode 0.1.2 → 0.2.0

package/README.md

@@ -1,49 +1,31 @@
 # omnicode
 
-The cross-platform command-line entrypoint for running OpenCode through OmniRoute.
+The cross-platform command-line entrypoint for running OpenCode through OmniRoute, backed by AI-powered reference indexing with Qdrant.
 
 ## What is omnicode?
 
-`omnicode` is a thin wrapper that launches OpenCode through OmniRoute. It expects you to install the underlying tools yourself, then handles optional GrayMatter and OpenSpec initialization, background OmniRoute lifecycle, and project-local OpenCode sessions. Developed and tested on Ubuntu Linux; cross-platform by design but untested on Windows, macOS, and other Linux distributions.
+`omnicode` is a wrapper that launches OpenCode through OmniRoute with zero friction. It handles GrayMatter memory, OpenSpec change tracking, and OmniRoute lifecycle automatically. On top of that, it indexes your `./references/` directory into a Qdrant vector database — unlocking semantic search for AI agents working in your codebase.
 
-## Why
-
-Because I'm lazy. Not "I'll automate this repetitive task" lazy, but "I keep opening a second terminal just to run `omniroute`, then manually init GrayMatter, then manually init OpenSpec, then forget which session ID I was using" lazy.
+Developed and tested on Ubuntu Linux; cross-platform by design (Node.js, no bash).
 
-Yes, I know OmniRoute is designed to run on a server. But I don't have a server at home, and I still want to save tokens by routing requests through it locally. Bonus: I get to use a bunch of free tiers from different providers without having to remember which API key goes where.
+## Why
 
-So I wrote this wrapper. It starts OmniRoute, inits GrayMatter and OpenSpec quietly in the background, remembers my session per project, and shuts everything down when I'm done. I run one command and pretend I'm a responsible developer with proper infrastructure.
+Because I kept opening a second terminal to run `omniroute`, manually init GrayMatter, manually init OpenSpec, and forget which session ID I was using. I wrote a wrapper so I can run one command and pretend I'm a responsible developer with proper infrastructure.
 
 ## Features
 
-- Thin npm global command written in Node.js (no bash needed).
-- Cross-platform by design: developed and tested on Ubuntu Linux; untested on Windows, macOS, and other Linux distributions.
-- Automatic session resume per project using the OpenCode database.
-- Background OmniRoute lifecycle with cleanup when OpenCode exits.
-- Quiet GrayMatter and OpenSpec initialization with captured logs.
-- Check runtime status with `omnicode --status`.
-- Print version with `omnicode --version`.
-
-## Requirements
-
-- Node.js 22 or later (developed and tested on Node 26; OmniRoute requires Node >=22 <=24).
-
-## Explore
-
-- [Getting Started](https://github.com/meyverick/omnicode/wiki/Getting-Started) - install, run, and uninstall.
-- [How it works](https://github.com/meyverick/omnicode/wiki/How-it-works) - runtime flow, session handling, and lifecycle.
-- [Configuration](https://github.com/meyverick/omnicode/wiki/Configuration) - paths and environment overrides.
-- [Troubleshooting](https://github.com/meyverick/omnicode/wiki/Troubleshooting) - common issues and rollback.
-
-## Acknowledgments
-
-Built on top of:
+- **Single command** — launches OmniRoute + OpenCode + optional tools in one shot.
+- **Automatic session resume** — remembers your session per project via the OpenCode database.
+- **Background OmniRoute lifecycle** — starts with OpenCode, stops when no sessions remain.
+- **Quiet initialization** — GrayMatter and OpenSpec init run in the background with captured logs.
+- **Semantic reference indexing** — indexes `./references/` into Qdrant with BGE embeddings for AI-agent search.
+- **Cross-platform runtime** — pure Node.js, no bash dependency.
 
-- [OpenCode](https://github.com/opencode-ai/opencode) - AI-powered coding assistant
-- [OmniRoute](https://github.com/diegosouzapw/OmniRoute) - model routing layer
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec) - AI agent workflow framework
-- [GrayMatter](https://github.com/angelnicolasc/graymatter) - persistent memory for AI agents
+## Quick start
 
-## License
+```bash
+npm install -g @meyverick/omnicode
+omnicode
+```
 
-[Apache 2.0](LICENSE)
+See the [wiki](https://github.com/meyverick/omnicode/wiki) for detailed setup, configuration, and troubleshooting.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meyverick/omnicode",
-  "version": "0.1.2",
-  "description": "Cross-platform command-line entrypoint for OpenCode through OmniRoute",
+  "version": "0.2.0",
+  "description": "Cross-platform CLI for OpenCode through OmniRoute with Qdrant semantic reference indexing",
   "type": "module",
   "bin": {
     "omnicode": "src/bin/omnicode.js"
@@ -22,5 +22,8 @@
     "cli"
   ],
   "author": "meyverick",
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "dependencies": {
+    "web-tree-sitter": "0.20.8"
+  }
 }

package/src/bin/omnicode-runtime.js

@@ -1,8 +1,12 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
-import { commandExists, getDataDir, isPidAlive, isProcessRunningAsync } from "../installer/lib.js";
+import { commandExists, getDataDir, isPidAlive, isProcessRunningAsync, detectQdrantMcp, generateQdrantConfig, ensureOpencodeConfig, ensureQdrantAgentInstructions, indexReferences, startMcpServer, stopMcpServer, getQdrantStoreEnv, getQdrantPidFile, isQdrantRunning, startQdrantContainer, stopQdrantContainer } from "../installer/lib.js";
+
+process.on("unhandledRejection", (err) => {
+  console.error("[omnicode] runtime: UNHANDLED REJECTION:", err?.message || err);
+});
 
 const MAX_OMNI_WAIT = 30;
 const OMNI_CHECK_DELAY = 1000;
@@ -21,15 +25,17 @@ async function initTool(name, args, logPath) {
   try {
     log = openSync(logPath, "w");
     const child = spawn(name, args, { stdio: ["ignore", log, log] });
+    let timer;
     const result = await Promise.race([
       new Promise((resolve) => {
         child.on("close", resolve);
         child.on("error", () => resolve(null));
       }),
       new Promise((resolve) => {
-        setTimeout(() => { child.kill(); resolve(null); }, 30000);
+        timer = setTimeout(() => { child.kill(); resolve(null); }, 30000);
       }),
     ]);
+    clearTimeout(timer);
     if (result === null) {
       console.log(`[omnicode] WARNING: ${name} init timed out; continuing. Log: ${logPath}`);
     } else if (result === 0) {
@@ -109,6 +115,8 @@ async function stopOmnirouteIfIdle(pidFile) {
     return;
   }
 
+  stopQdrantContainer();
+
   if (existsSync(pidFile)) {
     let pid = null;
     try {
@@ -141,8 +149,13 @@ export async function runRuntime(mode) {
     process.umask(0o077);
   }
 
-  const cleanup = async () => { await stopOmnirouteIfIdle(pidFile); };
+  let startedIndexing = false;
+  const cleanup = async () => {
+    if (startedIndexing) try { unlinkSync(join(process.cwd(), ".qdrant", ".indexing")); } catch {}
+    await stopOmnirouteIfIdle(pidFile);
+  };
   process.on("exit", () => {
+    if (startedIndexing) try { unlinkSync(join(process.cwd(), ".qdrant", ".indexing")); } catch {}
     try {
       if (!existsSync(pidFile)) return;
       const pid = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
@@ -159,26 +172,61 @@ export async function runRuntime(mode) {
 
   await Promise.all([
     pid !== null ? waitForOmniroute(pid, logFile) : Promise.resolve(),
+    startQdrantContainer(),
     initTools(dataDir),
   ]);
 
-  if (mode.flag === "-s" && mode.id) {
-    console.log(`[omnicode] launching opencode (session: ${mode.id})`);
-    await new Promise((resolve) => {
-      const child = spawn("opencode", ["-s", mode.id], {
-        stdio: "inherit",
-        cwd: process.cwd(),
-      });
-      child.on("close", () => resolve());
-    });
-  } else {
-    console.log("[omnicode] launching opencode (new session)");
-    await new Promise((resolve) => {
-      const child = spawn("opencode", [], {
-        stdio: "inherit",
-        cwd: process.cwd(),
+  const hasQdrant = detectQdrantMcp();
+  const refsDir = join(process.cwd(), "references");
+  let qdrantConfig = null;
+
+  if (hasQdrant) {
+    qdrantConfig = generateQdrantConfig();
+    ensureOpencodeConfig(qdrantConfig);
+    ensureQdrantAgentInstructions();
+    console.log("[omnicode] qdrant MCP configured");
+  }
+
+  const ac = new AbortController();
+  if (hasQdrant && existsSync(refsDir) && qdrantConfig) {
+    if (existsSync(join(process.cwd(), ".qdrant", ".indexing"))) {
+      console.log("[omnicode] background indexing is already running, skipping");
+    } else {
+      startedIndexing = true;
+      console.log("[omnicode] background indexing started");
+      indexReferences(refsDir, qdrantConfig, null, false, ac.signal).catch((err) => {
+        console.error(`[omnicode] background index failed: ${err.message}`);
       });
-      child.on("close", () => resolve());
-    });
+    }
   }
+
+  const launchOpencode = () => new Promise((resolve) => {
+    const args = mode.flag === "-s" && mode.id ? ["-s", mode.id] : [];
+    if (mode.flag === "-s" && mode.id) {
+      console.log(`[omnicode] launching opencode (session: ${mode.id})`);
+    } else {
+      console.log("[omnicode] launching opencode (new session)");
+    }
+    const child = spawn("opencode", args, { stdio: "inherit", cwd: process.cwd() });
+    const logFd = openSync(join(dataDir, "background.log"), "w");
+    const origLog = console.log;
+    const origWarn = console.warn;
+    const origError = console.error;
+    console.log = (...args) => writeSync(logFd, args.join(" ") + "\n");
+    console.warn = (...args) => writeSync(logFd, "WARN: " + args.join(" ") + "\n");
+    console.error = (...args) => writeSync(logFd, "ERROR: " + args.join(" ") + "\n");
+    child.on("close", () => {
+      setTimeout(() => {
+        console.log = origLog;
+        console.warn = origWarn;
+        console.error = origError;
+        try { closeSync(logFd); } catch {}
+        resolve();
+      }, 100);
+    });
+  });
+
+  await launchOpencode();
+  ac.abort();
+  await cleanup();
 }

package/src/bin/omnicode.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-import { readFileSync, realpathSync } from "node:fs";
+import { readFileSync, realpathSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { commandExists, getOpencodeDbPath, isProcessRunning } from "../installer/lib.js";
+process.on("unhandledRejection", (err) => {
+  console.error("[omnicode] UNHANDLED REJECTION:", err?.message || err);
+  process.exit(1);
+});
+
+import { commandExists, getOpencodeDbPath, isProcessRunning, detectQdrantMcp, generateQdrantConfig, ensureOpencodeConfig, indexReferences, isQdrantRunning, countProcesses, getQdrantRunningCount, countActiveIndexers } from "../installer/lib.js";
+import { downloadLanguageCmd } from "../installer/tree-sitter.js";
 import { runRuntime } from "./omnicode-runtime.js";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
@@ -19,7 +25,7 @@ try {
 }
 
 export function printUsage() {
-  console.log(`Usage: omnicode [-s <session_id>] [-c] [--status] [--version]`);
+  console.log(`Usage: omnicode [-s <session_id>] [-c] [--status] [--version] [index]`);
 }
 
 let _cachedVersion = null;
@@ -32,20 +38,28 @@ export function getVersion() {
 }
 
 export function getProcessStatus() {
+  const indexingLockPath = join(process.cwd(), ".qdrant", ".indexing");
   return {
-    opencode: isProcessRunning("opencode"),
-    omniroute: isProcessRunning("omniroute"),
+    opencode: countProcesses("opencode"),
+    omniroute: countProcesses("omniroute"),
+    qdrant: getQdrantRunningCount(),
+    indexing: existsSync(indexingLockPath),
+    indexingCount: countActiveIndexers(),
   };
 }
 
 export function printStatus(status = getProcessStatus()) {
-  console.log(`[omnicode] opencode: ${status.opencode ? "running" : "stopped"}`);
-  console.log(`[omnicode] omniroute: ${status.omniroute ? "running" : "stopped"}`);
+  console.log(`[omnicode] opencode: ${status.opencode > 0 ? `running (${status.opencode})` : "stopped"}`);
+  console.log(`[omnicode] omniroute: ${status.omniroute > 0 ? `running (${status.omniroute})` : "stopped"}`);
+  console.log(`[omnicode] qdrant: ${status.qdrant > 0 ? `running (${status.qdrant})` : "stopped"}`);
+  console.log(`[omnicode] indexing: ${status.indexing ? `true (${status.indexingCount})` : "false"}`);
 }
 
 export function parseArgs(argv) {
   let sessionId = null;
   let continueSession = false;
+  let index = false;
+  let forceReindex = false;
   for (let i = 2; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "-h" || arg === "--help") {
@@ -64,6 +78,22 @@ export function parseArgs(argv) {
       continueSession = true;
       continue;
     }
+    if (arg === "--force-reindex") {
+      forceReindex = true;
+      continue;
+    }
+    if (arg === "--index" || arg === "index") {
+      index = true;
+      continue;
+    }
+    if (arg === "download-language") {
+      const language = argv[++i];
+      if (!language) {
+        console.error("[omnicode] ERROR: download-language requires a language argument");
+        process.exit(2);
+      }
+      return { downloadLanguage: language };
+    }
     if (arg === "-s") {
       sessionId = argv[++i];
       if (!sessionId) {
@@ -83,7 +113,7 @@ export function parseArgs(argv) {
       process.exit(2);
     }
   }
-  return { sessionId, continueSession };
+  return { sessionId, continueSession, index, forceReindex };
 }
 
 export async function getLatestSessionId(directory = realpathSync(process.cwd())) {
@@ -113,6 +143,27 @@ export async function resolveSessionMode(sessionId, latestSessionId = null) {
 async function main() {
   const args = parseArgs(process.argv);
 
+  if (args.downloadLanguage) {
+    const success = await downloadLanguageCmd(args.downloadLanguage);
+    process.exit(success ? 0 : 1);
+  }
+
+  if (args.index) {
+    if (!detectQdrantMcp()) {
+      console.error("[omnicode] ERROR: uvx mcp-server-qdrant not found. Install uvx first.");
+      process.exit(1);
+    }
+    if (isQdrantRunning()) {
+      console.error("[omnicode] ERROR: a qdrant MCP server is already running for this project.");
+      console.error("[omnicode]        Close the opencode session first, or wait for indexing to finish.");
+      process.exit(1);
+    }
+    const qdrantConfig = generateQdrantConfig();
+    ensureOpencodeConfig(qdrantConfig);
+    await indexReferences(join(process.cwd(), "references"), qdrantConfig, null, args.forceReindex);
+    process.exit(0);
+  }
+
   const missing = ["opencode", "omniroute"].filter((cmd) => !commandExists(cmd));
   if (missing.length > 0) {
     console.error(`[omnicode] ERROR: missing required tool(s): ${missing.join(", ")}`);

package/src/installer/AGENTS.template.md

@@ -0,0 +1,13 @@
+<!-- qdrant:instructions:begin — managed by `omnicode`; edits inside this block are overwritten -->
+## Qdrant MCP (Semantic Search)
+
+Qdrant MCP [configured] -> execute semantic search over `./references/`.
+Index [maintained] via omnicode. Storage [isolated] -> `./.qdrant/` (local, zero external servers).
+Model -> `BAAI/bge-small-en-v1.5` (384 dimensions).
+
+- `qdrant-store(information, metadata?, collection_name?)` -> embed && store text chunk. `information` -> target text. Default collection -> `references`.
+- `qdrant-find(query, collection_name?)` -> execute semantic search via natural-language `query` -> retrieve optimal matches.
+
+**Execution Trigger [CRITICAL]:**
+Execute `qdrant-find` prior to codebase mutations -> retrieve reference context, architectural patterns, && documentation -> prevent hallucination.
+<!-- qdrant:instructions:end -->