gitnexus 1.4.7 → 1.4.8

package/README.md

@@ -2,7 +2,7 @@
 
 **Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
 
-Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+Works with **Cursor**, **Claude Code**, **Codex**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
 
 [![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -34,6 +34,7 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 |--------|-----|--------|---------------------|---------|
 | **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
 | **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Codex** | Yes | Yes | — | MCP + Skills |
 | **Windsurf** | Yes | — | — | MCP |
 | **OpenCode** | Yes | Yes | — | MCP + Skills |
 
@@ -55,6 +56,12 @@ If you prefer to configure manually instead of using `gitnexus setup`:
 claude mcp add gitnexus -- npx -y gitnexus@latest mcp
 ```
 
+### Codex (full support — MCP + skills)
+
+```bash
+codex mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -151,6 +158,20 @@ gitnexus wiki [path]             # Generate LLM-powered docs from knowledge grap
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 ```
 
+## Remote Embeddings
+
+Set these env vars to use a remote OpenAI-compatible `/v1/embeddings` endpoint instead of the local model:
+
+```bash
+export GITNEXUS_EMBEDDING_URL=http://your-server:8080/v1
+export GITNEXUS_EMBEDDING_MODEL=BAAI/bge-large-en-v1.5
+export GITNEXUS_EMBEDDING_DIMS=1024          # optional, default 384
+export GITNEXUS_EMBEDDING_API_KEY=your-key   # optional, default: "unused"
+gitnexus analyze . --embeddings
+```
+
+Works with Infinity, vLLM, TEI, llama.cpp, Ollama, LM Studio, or OpenAI. When unset, local embeddings are used unchanged.
+
 ## Multi-Repo Support
 
 GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.

package/dist/cli/ai-context.d.ts

@@ -2,7 +2,7 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import { type GeneratedSkillInfo } from './skill-gen.js';

package/dist/cli/ai-context.js

@@ -2,7 +2,7 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import fs from 'fs/promises';

package/dist/cli/analyze.d.ts

@@ -8,5 +8,7 @@ export interface AnalyzeOptions {
     embeddings?: boolean;
     skills?: boolean;
     verbose?: boolean;
+    /** Index the folder even when no .git directory is present. */
+    skipGit?: boolean;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -14,7 +14,7 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 // versions whose ABI is not yet supported by the native binary (#89).
 // disposeEmbedder intentionally not called — ONNX Runtime segfaults on cleanup (see #38)
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath, cleanupOldKuzuFiles } from '../storage/repo-manager.js';
-import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
+import { getCurrentCommit, getGitRoot, hasGitDir } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import { generateSkillFiles } from './skill-gen.js';
 import fs from 'fs/promises';
@@ -70,17 +70,27 @@ export const analyzeCommand = async (inputPath, options) => {
     else {
         const gitRoot = getGitRoot(process.cwd());
         if (!gitRoot) {
-            console.log('  Not inside a git repository\n');
-            process.exitCode = 1;
-            return;
+            if (!options?.skipGit) {
+                console.log('  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
+                process.exitCode = 1;
+                return;
+            }
+            // --skip-git: fall back to cwd as the root
+            repoPath = path.resolve(process.cwd());
+        }
+        else {
+            repoPath = gitRoot;
         }
-        repoPath = gitRoot;
     }
-    if (!isGitRepo(repoPath)) {
-        console.log('  Not a git repository\n');
+    const repoHasGit = hasGitDir(repoPath);
+    if (!repoHasGit && !options?.skipGit) {
+        console.log('  Not a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n');
         process.exitCode = 1;
         return;
     }
+    if (!repoHasGit) {
+        console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
+    }
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     // If kuzu existed but lbug doesn't, we're doing a migration re-index — say so.
@@ -88,11 +98,14 @@ export const analyzeCommand = async (inputPath, options) => {
     if (kuzuResult.found && kuzuResult.needsReindex) {
         console.log('  Migrating from KuzuDB to LadybugDB — rebuilding index...\n');
     }
-    const currentCommit = getCurrentCommit(repoPath);
+    const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
     const existingMeta = await loadMeta(storagePath);
     if (existingMeta && !options?.force && !options?.skills && existingMeta.lastCommit === currentCommit) {
-        console.log('  Already up to date\n');
-        return;
+        // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
+        if (currentCommit !== '') {
+            console.log('  Already up to date\n');
+            return;
+        }
     }
     if (process.env.GITNEXUS_NO_GITIGNORE) {
         console.log('  GITNEXUS_NO_GITIGNORE is set — skipping .gitignore (still reading .gitnexusignore)\n');
@@ -218,15 +231,26 @@ export const analyzeCommand = async (inputPath, options) => {
     const ftsTime = ((Date.now() - t0Fts) / 1000).toFixed(1);
     // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
     if (cachedEmbeddings.length > 0) {
-        updateBar(88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
-        const EMBED_BATCH = 200;
-        for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
-            const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
-            const paramsList = batch.map(e => ({ nodeId: e.nodeId, embedding: e.embedding }));
-            try {
-                await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+        // Check if cached embedding dimensions match current schema
+        const cachedDims = cachedEmbeddings[0].embedding.length;
+        const { EMBEDDING_DIMS } = await import('../core/lbug/schema.js');
+        if (cachedDims !== EMBEDDING_DIMS) {
+            // Dimensions changed (e.g. switched embedding model) — discard cache and re-embed all
+            console.error(`⚠️  Embedding dimensions changed (${cachedDims}d → ${EMBEDDING_DIMS}d), discarding cache`);
+            cachedEmbeddings = [];
+            cachedEmbeddingNodeIds = new Set();
+        }
+        else {
+            updateBar(88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
+            const EMBED_BATCH = 200;
+            for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
+                const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+                const paramsList = batch.map(e => ({ nodeId: e.nodeId, embedding: e.embedding }));
+                try {
+                    await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+                }
+                catch { /* some may fail if node was removed, that's fine */ }
             }
-            catch { /* some may fail if node was removed, that's fine */ }
         }
     }
     // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
@@ -243,12 +267,16 @@ export const analyzeCommand = async (inputPath, options) => {
         }
     }
     if (!embeddingSkipped) {
-        updateBar(90, 'Loading embedding model...');
+        const { isHttpMode } = await import('../core/embeddings/http-client.js');
+        const httpMode = isHttpMode();
+        updateBar(90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
         const t0Emb = Date.now();
         const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
         await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
             const scaled = 90 + Math.round((progress.percent / 100) * 8);
-            const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
+            const label = progress.phase === 'loading-model'
+                ? (httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...')
+                : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
             updateBar(scaled, label);
         }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
         embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
@@ -277,7 +305,12 @@ export const analyzeCommand = async (inputPath, options) => {
     };
     await saveMeta(storagePath, meta);
     await registerRepo(repoPath, meta);
-    await addToGitignore(repoPath);
+    // Only attempt to update .gitignore when a .git directory is present.
+    // Use hasGitDir (filesystem check) rather than git CLI subprocess
+    // so we skip correctly for --skip-git folders even if git CLI is available.
+    if (hasGitDir(repoPath)) {
+        await addToGitignore(repoPath);
+    }
     const projectName = path.basename(repoPath);
     let aggregatedClusterCount = 0;
     if (pipelineResult.communityResult?.communities) {

package/dist/cli/index.js

@@ -13,7 +13,7 @@ program
     .version(pkg.version);
 program
     .command('setup')
-    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode')
+    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('analyze [path]')
@@ -21,6 +21,7 @@ program
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
     .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('--skip-git', 'Index a folder without requiring a .git directory')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .addHelpText('after', '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));

package/dist/cli/setup.js

@@ -8,11 +8,14 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
 import { getGlobalDir } from '../storage/repo-manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const execFileAsync = promisify(execFile);
 /**
  * The MCP server entry for all editors.
  * On Windows, npx must be invoked via cmd /c since it's a .cmd script.
@@ -201,11 +204,65 @@ async function setupOpenCode(result) {
         result.errors.push(`OpenCode: ${err.message}`);
     }
 }
+/**
+ * Build a TOML section for Codex MCP config (~/.codex/config.toml).
+ */
+function getCodexMcpTomlSection() {
+    const entry = getMcpEntry();
+    const command = JSON.stringify(entry.command);
+    const args = `[${entry.args.map(arg => JSON.stringify(arg)).join(', ')}]`;
+    return `[mcp_servers.gitnexus]\ncommand = ${command}\nargs = ${args}\n`;
+}
+/**
+ * Append GitNexus MCP server config to Codex's config.toml if missing.
+ */
+async function upsertCodexConfigToml(configPath) {
+    let existing = '';
+    try {
+        existing = await fs.readFile(configPath, 'utf-8');
+    }
+    catch {
+        existing = '';
+    }
+    if (existing.includes('[mcp_servers.gitnexus]')) {
+        return;
+    }
+    const section = getCodexMcpTomlSection();
+    const nextContent = existing.trim().length > 0
+        ? `${existing.trimEnd()}\n\n${section}`
+        : section;
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, `${nextContent.trimEnd()}\n`, 'utf-8');
+}
+async function setupCodex(result) {
+    const codexDir = path.join(os.homedir(), '.codex');
+    if (!(await dirExists(codexDir))) {
+        result.skipped.push('Codex (not installed)');
+        return;
+    }
+    try {
+        const entry = getMcpEntry();
+        await execFileAsync('codex', ['mcp', 'add', 'gitnexus', '--', entry.command, ...entry.args], { shell: process.platform === 'win32' });
+        result.configured.push('Codex');
+        return;
+    }
+    catch {
+        // Fallback for environments where `codex` binary isn't on PATH.
+    }
+    try {
+        const configPath = path.join(codexDir, 'config.toml');
+        await upsertCodexConfigToml(configPath);
+        result.configured.push('Codex (MCP added to ~/.codex/config.toml)');
+    }
+    catch (err) {
+        result.errors.push(`Codex: ${err.message}`);
+    }
+}
 // ─── Skill Installation ───────────────────────────────────────────
 /**
  * Install GitNexus skills to a target directory.
  * Each skill is installed as {targetDir}/gitnexus-{skillName}/SKILL.md
- * following the Agent Skills standard (both Cursor and Claude Code).
+ * following the Agent Skills standard (Cursor, Claude Code, and Codex).
  *
  * Supports two source layouts:
  *   - Flat file:  skills/{name}.md           → copied as SKILL.md
@@ -310,6 +367,24 @@ async function installOpenCodeSkills(result) {
         result.errors.push(`OpenCode skills: ${err.message}`);
     }
 }
+/**
+ * Install global Codex skills to ~/.agents/skills/gitnexus/
+ */
+async function installCodexSkills(result) {
+    const codexDir = path.join(os.homedir(), '.codex');
+    if (!(await dirExists(codexDir)))
+        return;
+    const skillsDir = path.join(os.homedir(), '.agents', 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Codex skills (${installed.length} skills → ~/.agents/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Codex skills: ${err.message}`);
+    }
+}
 // ─── Main command ──────────────────────────────────────────────────
 export const setupCommand = async () => {
     console.log('');
@@ -328,11 +403,13 @@ export const setupCommand = async () => {
     await setupCursor(result);
     await setupClaudeCode(result);
     await setupOpenCode(result);
+    await setupCodex(result);
     // Install global skills for platforms that support them
     await installClaudeCodeSkills(result);
     await installClaudeCodeHooks(result);
     await installCursorSkills(result);
     await installOpenCodeSkills(result);
+    await installCodexSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');

package/dist/config/supported-languages.d.ts

@@ -1,3 +1,33 @@
+/**
+ * HOW TO ADD A NEW LANGUAGE:
+ *
+ * 1. Add the enum member below (e.g., Scala = 'scala')
+ * 2. Run `tsc --noEmit` — compiler errors guide you to every dispatch table
+ * 3. Use this checklist for each file:
+ *
+ *    FILE                              | WHAT TO ADD                              | DEFAULT (simple languages)
+ *    ----------------------------------|------------------------------------------|---------------------------
+ *    tree-sitter-queries.ts            | Query string + LANGUAGE_QUERIES entry    | (required)
+ *    export-detection.ts               | ExportChecker function + table entry     | (required)
+ *    import-resolution.ts              | Resolver in importResolvers              | resolveStandard(...)
+ *    import-resolution.ts              | namedBindingExtractors entry             | undefined
+ *    call-routing.ts                   | callRouters entry                        | noRouting
+ *    entry-point-scoring.ts            | ENTRY_POINT_PATTERNS entry               | []
+ *    framework-detection.ts            | AST_FRAMEWORK_PATTERNS entry             | []
+ *    type-extractors/<lang>.ts         | New file + index.ts import               | (required)
+ *    resolvers/<lang>.ts               | Resolver file (if non-standard)          | (only if resolveStandard insufficient)
+ *    named-binding-extraction.ts       | Extractor (if named imports)             | (only if language has named imports)
+ *
+ * 4. Also check these files for language-specific if-checks (no compile-time guard):
+ *    - mro-processor.ts (MRO strategy selection)
+ *    - heritage-processor.ts (extends/implements handling)
+ *    - parse-worker.ts (AST edge cases)
+ *    - parsing-processor.ts (node label normalization)
+ *
+ * 5. Add tree-sitter-<lang> to package.json dependencies
+ * 6. Add file extension mapping in utils.ts getLanguageFromFilename()
+ * 7. Run full test suite
+ */
 export declare enum SupportedLanguages {
     JavaScript = "javascript",
     TypeScript = "typescript",

package/dist/config/supported-languages.js

@@ -1,3 +1,33 @@
+/**
+ * HOW TO ADD A NEW LANGUAGE:
+ *
+ * 1. Add the enum member below (e.g., Scala = 'scala')
+ * 2. Run `tsc --noEmit` — compiler errors guide you to every dispatch table
+ * 3. Use this checklist for each file:
+ *
+ *    FILE                              | WHAT TO ADD                              | DEFAULT (simple languages)
+ *    ----------------------------------|------------------------------------------|---------------------------
+ *    tree-sitter-queries.ts            | Query string + LANGUAGE_QUERIES entry    | (required)
+ *    export-detection.ts               | ExportChecker function + table entry     | (required)
+ *    import-resolution.ts              | Resolver in importResolvers              | resolveStandard(...)
+ *    import-resolution.ts              | namedBindingExtractors entry             | undefined
+ *    call-routing.ts                   | callRouters entry                        | noRouting
+ *    entry-point-scoring.ts            | ENTRY_POINT_PATTERNS entry               | []
+ *    framework-detection.ts            | AST_FRAMEWORK_PATTERNS entry             | []
+ *    type-extractors/<lang>.ts         | New file + index.ts import               | (required)
+ *    resolvers/<lang>.ts               | Resolver file (if non-standard)          | (only if resolveStandard insufficient)
+ *    named-binding-extraction.ts       | Extractor (if named imports)             | (only if language has named imports)
+ *
+ * 4. Also check these files for language-specific if-checks (no compile-time guard):
+ *    - mro-processor.ts (MRO strategy selection)
+ *    - heritage-processor.ts (extends/implements handling)
+ *    - parse-worker.ts (AST edge cases)
+ *    - parsing-processor.ts (node label normalization)
+ *
+ * 5. Add tree-sitter-<lang> to package.json dependencies
+ * 6. Add file extension mapping in utils.ts getLanguageFromFilename()
+ * 7. Run full test suite
+ */
 export var SupportedLanguages;
 (function (SupportedLanguages) {
     SupportedLanguages["JavaScript"] = "javascript";

package/dist/core/embeddings/embedder.d.ts

@@ -30,6 +30,11 @@ export declare const initEmbedder: (onProgress?: ModelProgressCallback, config?:
  * Check if the embedder is initialized and ready
  */
 export declare const isEmbedderReady: () => boolean;
+/**
+ * Get the effective embedding dimensions.
+ * In HTTP mode, uses GITNEXUS_EMBEDDING_DIMS if set, otherwise the default.
+ */
+export declare const getEmbeddingDimensions: () => number;
 /**
  * Get the embedder instance (throws if not initialized)
  */
@@ -38,7 +43,7 @@ export declare const getEmbedder: () => FeatureExtractionPipeline;
  * Embed a single text string
  *
  * @param text - Text to embed
- * @returns Float32Array of embedding vector (384 dimensions)
+ * @returns Float32Array of embedding vector
  */
 export declare const embedText: (text: string) => Promise<Float32Array>;
 /**

package/dist/core/embeddings/embedder.js

@@ -15,17 +15,53 @@ if (!process.env.ORT_LOG_LEVEL) {
 import { pipeline, env } from '@huggingface/transformers';
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
+/**
+ * Check whether the onnxruntime-node package that @huggingface/transformers
+ * will actually load at runtime ships the CUDA execution provider.
+ *
+ * Critical: we resolve from transformers' own module scope, NOT from ours.
+ * npm may install two copies — a top-level 1.24.x (our dep) and a nested
+ * 1.21.0 (transformers' pinned dep). The guard must inspect whichever copy
+ * transformers.js will dlopen, otherwise the check is meaningless.
+ */
+function hasOrtCudaProvider() {
+    try {
+        const require = createRequire(import.meta.url);
+        // Resolve from @huggingface/transformers' scope so we find the same
+        // onnxruntime-node binary that transformers.js will use at runtime
+        const transformersDir = dirname(require.resolve('@huggingface/transformers/package.json'));
+        const ortRequire = createRequire(join(transformersDir, 'package.json'));
+        const ortPath = dirname(ortRequire.resolve('onnxruntime-node/package.json'));
+        // ORT 1.24.x only ships CUDA binaries for linux/x64 (downloaded from NuGet
+        // at postinstall). arm64 will correctly return false here until ORT adds support.
+        const arch = process.arch;
+        return existsSync(join(ortPath, 'bin', 'napi-v6', 'linux', arch, 'libonnxruntime_providers_cuda.so'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check whether CUDA libraries are actually available on this system.
  * ONNX Runtime's native layer crashes (uncatchable) if we attempt CUDA
  * without the required shared libraries, so we probe first.
  *
- * Checks the dynamic linker cache (ldconfig) which covers all architectures
- * and install paths, then falls back to CUDA_PATH / LD_LIBRARY_PATH env vars.
+ * Checks both:
+ * 1. That system CUDA libraries (libcublasLt) are present
+ * 2. That onnxruntime-node ships the CUDA execution provider binary
+ *
+ * Both conditions must be true — system CUDA libs alone are not enough
+ * if onnxruntime-node is a CPU-only build (versions < 1.24.0).
  */
 function isCudaAvailable() {
+    // First, verify onnxruntime-node has the CUDA provider binary.
+    // Without this, requesting CUDA causes an uncatchable native crash.
+    if (!hasOrtCudaProvider())
+        return false;
     // Primary: query the dynamic linker cache — covers all architectures,
     // distro layouts, and custom install paths registered with ldconfig
     try {
@@ -70,6 +106,10 @@ export const getCurrentDevice = () => currentDevice;
  * @returns Promise resolving to the embedder pipeline
  */
 export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
+    if (isHttpMode()) {
+        throw new Error('initEmbedder() should not be called in HTTP mode. ' +
+            'Use embedText()/embedBatch() which handle HTTP transparently.');
+    }
     // Return existing instance if available
     if (embedderInstance) {
         return embedderInstance;
@@ -169,12 +209,25 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
  * Check if the embedder is initialized and ready
  */
 export const isEmbedderReady = () => {
-    return embedderInstance !== null;
+    return isHttpMode() || embedderInstance !== null;
+};
+/**
+ * Get the effective embedding dimensions.
+ * In HTTP mode, uses GITNEXUS_EMBEDDING_DIMS if set, otherwise the default.
+ */
+export const getEmbeddingDimensions = () => {
+    if (isHttpMode()) {
+        return getHttpDimensions() ?? DEFAULT_EMBEDDING_CONFIG.dimensions;
+    }
+    return DEFAULT_EMBEDDING_CONFIG.dimensions;
 };
 /**
  * Get the embedder instance (throws if not initialized)
  */
 export const getEmbedder = () => {
+    if (isHttpMode()) {
+        throw new Error('getEmbedder() is not available in HTTP embedding mode. Use embedText()/embedBatch() instead.');
+    }
     if (!embedderInstance) {
         throw new Error('Embedder not initialized. Call initEmbedder() first.');
     }
@@ -184,9 +237,13 @@ export const getEmbedder = () => {
  * Embed a single text string
  *
  * @param text - Text to embed
- * @returns Float32Array of embedding vector (384 dimensions)
+ * @returns Float32Array of embedding vector
  */
 export const embedText = async (text) => {
+    if (isHttpMode()) {
+        const [vec] = await httpEmbed([text]);
+        return vec;
+    }
     const embedder = getEmbedder();
     const result = await embedder(text, {
         pooling: 'mean',
@@ -206,6 +263,9 @@ export const embedBatch = async (texts) => {
     if (texts.length === 0) {
         return [];
     }
+    if (isHttpMode()) {
+        return httpEmbed(texts);
+    }
     const embedder = getEmbedder();
     // Process batch
     const result = await embedder(texts, {

package/dist/core/embeddings/embedding-pipeline.js

@@ -121,14 +121,16 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             percent: 0,
             modelDownloadPercent: 0,
         });
-        await initEmbedder((modelProgress) => {
-            const downloadPercent = modelProgress.progress ?? 0;
-            onProgress({
-                phase: 'loading-model',
-                percent: Math.round(downloadPercent * 0.2),
-                modelDownloadPercent: downloadPercent,
-            });
-        }, finalConfig);
+        if (!isEmbedderReady()) {
+            await initEmbedder((modelProgress) => {
+                const downloadPercent = modelProgress.progress ?? 0;
+                onProgress({
+                    phase: 'loading-model',
+                    percent: Math.round(downloadPercent * 0.2),
+                    modelDownloadPercent: downloadPercent,
+                });
+            }, finalConfig);
+        }
         onProgress({
             phase: 'loading-model',
             percent: 20,
@@ -255,7 +257,7 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     // Query the vector index on CodeEmbedding to get nodeIds and distances
     const vectorQuery = `
     CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
-      CAST(${queryVecStr} AS FLOAT[384]), ${k})
+      CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${k})
     YIELD node AS emb, distance
     WITH emb, distance
     WHERE distance < ${maxDistance}

package/dist/core/embeddings/http-client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTTP Embedding Client
+ *
+ * Shared fetch+retry logic for OpenAI-compatible /v1/embeddings endpoints.
+ * Imported by both the core embedder (batch) and MCP embedder (query).
+ */
+/**
+ * Check whether HTTP embedding mode is active (env vars are set).
+ */
+export declare const isHttpMode: () => boolean;
+/**
+ * Return the configured embedding dimensions for HTTP mode, or undefined
+ * if HTTP mode is not active or no explicit dimensions are set.
+ */
+export declare const getHttpDimensions: () => number | undefined;
+/**
+ * Embed texts via the HTTP backend, splitting into batches.
+ * Reads config from env vars on every call.
+ *
+ * @param texts - Array of texts to embed
+ * @returns Array of Float32Array embedding vectors
+ */
+export declare const httpEmbed: (texts: string[]) => Promise<Float32Array[]>;
+/**
+ * Embed a single query text via the HTTP backend.
+ * Convenience for MCP search where only one vector is needed.
+ *
+ * @param text - Query text to embed
+ * @returns Embedding vector as number array
+ */
+export declare const httpEmbedQuery: (text: string) => Promise<number[]>;