gitnexus 1.6.10-rc.1 → 1.6.10-rc.3

package/README.md

@@ -43,13 +43,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Claude Code**          | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                             | **Full**     |
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
-| **Codex**                | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Codex**                | Yes | Yes    | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks))   | **Full**     |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ### Community Integrations
 
@@ -71,12 +71,23 @@ claude mcp add gitnexus -- npx -y gitnexus@latest mcp
 claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp
 ```
 
-### Codex (full support — MCP + skills)
+### Codex (full support — MCP + skills + hooks)
 
 ```bash
 codex mcp add gitnexus -- npx -y gitnexus@latest mcp
 ```
 
+Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in `~/.codex/hooks.json`, [same schema as Claude Code](https://developers.openai.com/codex/hooks)) need the bundled adapter script, so they are installed by `gitnexus setup -c codex` rather than manually.
+
+Alternatively, install everything as a [Codex plugin](https://developers.openai.com/codex/plugins/build) (MCP + skills + hooks in one step):
+
+```bash
+codex plugin marketplace add abhigyanpatwari/GitNexus
+# then inside Codex: /plugins → install "GitNexus"
+```
+
+> **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -209,6 +220,7 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
@@ -409,6 +421,27 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Installation fails behind an HTTP proxy (`onnxruntime-node` postinstall)
+
+`onnxruntime-node`'s postinstall downloads optional CUDA GPU binaries from `api.nuget.org` — outside the npm registry, so registry mirrors don't cover it, and its proxy layer (`global-agent`) ignores the standard `HTTP_PROXY`/`HTTPS_PROXY` variables and rejects 302 redirects ([#2370](https://github.com/abhigyanpatwari/GitNexus/issues/2370)).
+
+Since the packages are optional dependencies, a failed download no longer breaks `npm install -g gitnexus` — npm skips the embedding stack and everything else works. The stack then **self-heals on demand**: the first `gitnexus analyze --embeddings` (or an explicit `gitnexus embeddings install`) fetches it through your configured npm registry — mirrors and proxies apply, no NuGet download involved — into `~/.gitnexus/embedding-runtime`.
+
+```bash
+# heal a proxy-degraded install manually (CPU embeddings; registry-only)
+gitnexus embeddings install
+
+# reinstall into the prefix even when the stack already resolves
+gitnexus embeddings install --force
+
+# CUDA GPU hosts: also fetch GPU binaries (NuGet; set the proxy global-agent reads)
+GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> gitnexus embeddings install --cuda
+```
+
+The prefix defaults to `~/.gitnexus/embedding-runtime`; set `GITNEXUS_EMBEDDING_RUNTIME_DIR` to install it elsewhere (e.g. a writable path in a container).
+
+> **Node requirement for the on-demand prefix:** the self-heal loads the prefixed packages via `module.registerHooks`, available on Node **≥ 22.15** (on the 22.x line) or **≥ 23.5** (on the 23.x line). On an older Node the packages install but can't be loaded from the prefix — reinstall them into the install itself instead (works on every supported Node): `ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus` (Windows: `set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus`). Skipping only the CUDA download keeps full CPU embeddings (CPU embeddings don't need it). Check the result any time with `gitnexus doctor` (Embeddings → Support line).
+
 ### Analyze warns about unavailable FTS or VECTOR extensions
 
 GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.

package/dist/cli/analyze.js

@@ -27,8 +27,9 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { safeUrl } from '../core/embeddings/http-client.js';
-import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { isHttpMode, safeUrl } from '../core/embeddings/http-client.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -797,6 +798,52 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: custom HTTP embeddings require BOTH --embedding-base-url and --embedding-model ' +
             '(or the matching env vars). Falling back to local ONNX embeddings.\n');
     }
+    // On-demand embedding runtime (#2370): when the optional stack was pruned at
+    // install time (proxy-blocked NuGet download in onnxruntime-node's
+    // postinstall), heal it here instead of failing later in the pipeline. The
+    // install goes through the user's npm registry config (mirrors/proxies
+    // apply) with --ignore-scripts, so no NuGet download is attempted. Runs
+    // before bar.start() like the sibling validations above.
+    if (embeddingsEnabled && !isHttpMode()) {
+        const resolved = resolveEmbeddingRuntime();
+        // Resolved-but-unloadable (a populated prefix on a Node with no
+        // module.registerHooks), or nothing installed on such a Node: fail fast with
+        // capability guidance instead of dying mid-pipeline over an unusable prefix
+        // or downloading a runtime the loader can't reach. A package-sourced stack
+        // never needs the hook, so it is excluded. --embeddings was explicitly
+        // requested and this failure is deterministic, so fail fast rather than
+        // silently degrading to BM25 (distinct from a transient install timeout).
+        if (!isPrefixRuntimeLoadable() && (resolved === null || resolved.source === 'runtime-prefix')) {
+            cliError(`  ${localEmbeddingPrefixUnloadableMessage().replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // On-demand embedding runtime (#2370): when the optional stack was pruned at
+        // install time (proxy-blocked NuGet download in onnxruntime-node's
+        // postinstall), heal it here instead of failing later in the pipeline. The
+        // install goes through the user's npm registry config (mirrors/proxies
+        // apply) with --ignore-scripts, so no NuGet download is attempted.
+        if (resolved === null) {
+            console.log(`  Local embedding runtime is not installed (optional packages were skipped at install time).\n` +
+                `  Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …\n` +
+                `  (one-time; rerun manually anytime with \`gitnexus embeddings install\`)\n`);
+            try {
+                // Short deadline (env override still wins): analyze is interactive, so a
+                // blackholed proxy must not stall the whole index run for the 10-minute
+                // default — fail over to the guidance below instead.
+                await installEmbeddingRuntime({}, getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS));
+                console.log('  Embedding runtime installed.\n');
+            }
+            catch (err) {
+                cliError(`  Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `  ${localEmbeddingStackMissingMessage().replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'local-embedding-stack-missing' });
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
@@ -1203,6 +1250,18 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // The optional embedding stack (@huggingface/transformers → onnxruntime-node)
+        // was pruned at install time — usually a proxy-blocked NuGet download during
+        // onnxruntime-node's postinstall (#2370). Checked before the generic
+        // module-not-found "installation may be corrupt" hint below, which would
+        // otherwise misdiagnose a deliberate optional-dependency skip.
+        if (isMissingLocalEmbeddingStackMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -14,6 +15,10 @@ export declare function localEmbeddingDoctorStatus(opts: {
     httpMode: boolean;
     platform?: NodeJS.Platform;
     arch?: NodeJS.Architecture;
+    /** Injectable for tests; defaults to probing the real install. */
+    resolution?: EmbeddingRuntimeResolution | null;
+    /** Injectable for tests; defaults to this Node's registerHooks capability. */
+    prefixLoadable?: boolean;
 }): {
     status: string;
     detail: string | null;

package/dist/cli/doctor.js

@@ -1,7 +1,8 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
-import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
 import { checkLbugNative } from '../core/lbug/native-check.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
@@ -64,6 +65,25 @@ export function localEmbeddingDoctorStatus(opts) {
     if (blocker) {
         return { status: `✗ local embeddings unavailable on ${platform}/${arch}`, detail: blocker };
     }
+    // The stack is an optionalDependency — npm prunes it when onnxruntime-node's
+    // postinstall can't download its CUDA binaries (proxy/firewall, #2370).
+    const resolution = opts.resolution !== undefined ? opts.resolution : resolveEmbeddingRuntime();
+    if (resolution === null) {
+        return {
+            status: '✗ optional embedding stack not installed',
+            detail: localEmbeddingStackMissingMessage(),
+        };
+    }
+    // A prefix-sourced stack needs module.registerHooks to load; on Node < 22.15 /
+    // < 23.5 it is present but unreachable (#2372). Report loadability, not bare
+    // presence, so the diagnostic stops claiming a ✓ the loader can't honour.
+    const prefixLoadable = opts.prefixLoadable ?? isPrefixRuntimeLoadable();
+    if (resolution.source === 'runtime-prefix' && !prefixLoadable) {
+        return {
+            status: '✗ embedding stack installed in the prefix but not loadable on this Node',
+            detail: localEmbeddingPrefixUnloadableMessage(),
+        };
+    }
     return { status: '✓ local embeddings supported', detail: null };
 }
 export const doctorCommand = async () => {

package/dist/cli/editor-targets.js

@@ -102,6 +102,17 @@ export function getEditorTargets(home = os.homedir()) {
             needle: 'gitnexus-hook',
             scriptDir: path.join(home, '.claude', 'hooks', 'gitnexus'),
         },
+        {
+            id: 'codex',
+            label: 'Codex',
+            // Codex hooks use Claude Code's exact {hooks: {Event: [...]}} JSON shape
+            // and hookSpecificOutput response contract, in a dedicated hooks.json
+            // (https://developers.openai.com/codex/hooks).
+            settingsFile: path.join(home, '.codex', 'hooks.json'),
+            events: ['PreToolUse', 'PostToolUse'],
+            needle: 'gitnexus-hook',
+            scriptDir: path.join(home, '.codex', 'hooks', 'gitnexus'),
+        },
         {
             id: 'antigravity',
             label: 'Antigravity',

package/dist/cli/embeddings.d.ts

@@ -0,0 +1,12 @@
+export interface EmbeddingsInstallOptions {
+    cuda?: boolean;
+    force?: boolean;
+}
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export declare const embeddingsInstallCommand: (options?: EmbeddingsInstallOptions) => Promise<void>;

package/dist/cli/embeddings.js

@@ -0,0 +1,49 @@
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { getEmbeddingRuntimeDir, getEmbeddingStackSpecs, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
+import { localEmbeddingPrefixUnloadableMessage } from '../core/embeddings/runtime-support.js';
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export const embeddingsInstallCommand = async (options = {}) => {
+    const resolved = resolveEmbeddingRuntime();
+    if (resolved?.source === 'package' && !options.force) {
+        cliInfo('The embedding stack is already installed with gitnexus itself — nothing to do.\n' +
+            '(Use --force to install a copy into the runtime prefix anyway.)');
+        return;
+    }
+    const specs = Object.entries(getEmbeddingStackSpecs())
+        .map(([name, spec]) => `${name}@${spec}`)
+        .join(', ');
+    cliInfo(`Installing ${specs} into ${getEmbeddingRuntimeDir()} …`);
+    cliInfo(options.cuda
+        ? 'CUDA mode: onnxruntime-node will download GPU binaries from NuGet ' +
+            '(set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> behind a proxy).'
+        : 'CPU mode: install scripts are skipped — only your npm registry is contacted.');
+    try {
+        await installEmbeddingRuntime({ cuda: options.cuda, onOutput: (line) => cliInfo(`  ${line}`) });
+    }
+    catch (err) {
+        cliError(`${err instanceof Error ? err.message : String(err)}\n`, {
+            recoveryHint: 'local-embedding-stack-missing',
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const postInstall = resolveEmbeddingRuntime();
+    if (postInstall === null) {
+        cliInfo('✗ Install completed but the stack still does not resolve — check the output above.');
+        process.exitCode = 1;
+        return;
+    }
+    if (postInstall.source === 'runtime-prefix' && !isPrefixRuntimeLoadable()) {
+        // The packages are in the prefix, but this Node has no module.registerHooks
+        // to load them — don't claim readiness the loader can't honour.
+        cliWarn(`${localEmbeddingPrefixUnloadableMessage()}\n`);
+        return;
+    }
+    cliInfo('✓ Embedding runtime installed. `gitnexus analyze --embeddings` is ready.');
+};

package/dist/cli/help-i18n.js

@@ -17,6 +17,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     list: 'help.command.list.description',
     status: 'help.command.status.description',
     doctor: 'help.command.doctor.description',
+    embeddings: 'help.command.embeddings.description',
+    'embeddings install': 'help.command.embeddings.install.description',
     clean: 'help.command.clean.description',
     remove: 'help.command.remove.description',
     wiki: 'help.command.wiki.description',
@@ -143,6 +145,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',
+    'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
+    'embeddings install|--force': 'help.option.embeddings.install.force',
     'group create|--force': 'help.option.group.create.force',
     'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
     'group sync|--exact-only': 'help.option.group.sync.exactOnly',

package/dist/cli/i18n/en.d.ts

@@ -117,6 +117,8 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+    readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
     readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
     readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -220,6 +222,8 @@ export declare const en: {
     readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+    readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+    readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
     readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
     readonly 'help.option.group.sync.exactOnly': "Exact match only";

package/dist/cli/i18n/en.js

@@ -117,6 +117,8 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
+    'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',
     'help.command.remove.description': 'Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.',
     'help.command.wiki.description': 'Generate repository wiki from knowledge graph',
@@ -220,6 +222,8 @@ export const en = {
     'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
+    'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
+    'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
     'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
     'help.option.group.sync.exactOnly': 'Exact match only',

package/dist/cli/i18n/resources.d.ts

@@ -118,6 +118,8 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+        readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
         readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
         readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -221,6 +223,8 @@ export declare const cliResources: {
         readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+        readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+        readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
         readonly 'help.option.group.create.force': "Overwrite existing group";
         readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
         readonly 'help.option.group.sync.exactOnly': "Exact match only";
@@ -360,6 +364,8 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.embeddings.description': string;
+        'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;
         'help.command.remove.description': string;
         'help.command.wiki.description': string;
@@ -463,6 +469,8 @@ export declare const cliResources: {
         'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
+        'help.option.embeddings.install.cuda': string;
+        'help.option.embeddings.install.force': string;
         'help.option.group.create.force': string;
         'help.option.group.sync.skipEmbeddings': string;
         'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -117,6 +117,8 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.embeddings.description': string;
+    'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;
     'help.command.remove.description': string;
     'help.command.wiki.description': string;
@@ -220,6 +222,8 @@ export declare const zhCN: {
     'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
+    'help.option.embeddings.install.cuda': string;
+    'help.option.embeddings.install.force': string;
     'help.option.group.create.force': string;
     'help.option.group.sync.skipEmbeddings': string;
     'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.js

@@ -117,6 +117,8 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
+    'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',
     'help.command.remove.description': '删除已注册仓库的 GitNexus 索引（按别名、名称或绝对路径）。与 `clean` 不同，不要求位于仓库内；未知目标会幂等处理。',
     'help.command.wiki.description': '从知识图谱生成仓库 Wiki',
@@ -220,6 +222,8 @@ export const zhCN = {
     'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
+    'help.option.embeddings.install.cuda': '同时下载 CUDA GPU 二进制文件（运行 onnxruntime-node 的 NuGet postinstall；代理后请设置 GLOBAL_AGENT_HTTPS_PROXY）',
+    'help.option.embeddings.install.force': '即使嵌入组件已可解析，也强制安装到运行时目录',
     'help.option.group.create.force': '覆盖现有仓库组',
     'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25（不使用嵌入回退）',
     'help.option.group.sync.exactOnly': '仅精确匹配',

package/dist/cli/index.js

@@ -153,6 +153,17 @@ program
     .command('doctor')
     .description('Show runtime platform capabilities and embedding configuration')
     .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+program
+    .command('embeddings')
+    .description('Manage the on-demand local embedding runtime')
+    .command('install')
+    .description('Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. ' +
+    'Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). ' +
+    'Downloads only from your configured npm registry — mirrors and proxies apply.')
+    .option('--cuda', "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; " +
+    'set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)')
+    .option('--force', 'Install into the runtime prefix even when the stack already resolves')
+    .action(createLazyAction(() => import('./embeddings.js'), 'embeddingsInstallCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')

package/dist/cli/setup.js

@@ -407,20 +407,26 @@ export async function copyHookHelpers(srcDir, destDir, label, result) {
     return failedRequired;
 }
 /**
- * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
- * Merges hook config without overwriting existing hooks, preserving
- * comments and formatting in the JSONC file.
+ * Install GitNexus hooks for editors that use Claude Code's hooks schema.
+ *
+ * Claude Code registers hooks in ~/.claude/settings.json; Codex uses a
+ * dedicated ~/.codex/hooks.json with the identical {hooks: {Event: [...]}}
+ * JSON shape, stdin payload, and hookSpecificOutput response contract
+ * (https://developers.openai.com/codex/hooks), so both runtimes share this
+ * installer and the same bundled adapter script. Merges hook config without
+ * overwriting existing hooks, preserving comments and formatting.
  */
-async function installClaudeCodeHooks(result) {
-    const claudeDir = path.join(os.homedir(), '.claude');
-    if (!(await dirExists(claudeDir)))
+async function installClaudeSchemaHooks(result, id) {
+    const hookCfg = hookTarget(id);
+    const settingsPath = hookCfg.settingsFile;
+    const label = `${hookCfg.label} hooks`;
+    // Gate on the editor's own config dir (~/.claude, ~/.codex) existing.
+    if (!(await dirExists(path.dirname(settingsPath))))
         return;
-    const claudeHook = hookTarget('claude');
-    const settingsPath = claudeHook.settingsFile;
     // Source hooks bundled within the gitnexus package (hooks/claude/)
     const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
-    // Copy unified hook script to ~/.claude/hooks/gitnexus/
-    const destHooksDir = claudeHook.scriptDir;
+    // Copy unified hook script to the editor's hooks/gitnexus/ dir
+    const destHooksDir = hookCfg.scriptDir;
     try {
         await fs.mkdir(destHooksDir, { recursive: true });
         const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
@@ -431,7 +437,7 @@ async function installClaudeCodeHooks(result) {
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
             const jsonCli = JSON.stringify(normalizedCli);
             if (!content.includes(CLI_PATH_SOURCE_LITERAL)) {
-                result.errors.push('Claude Code hooks: gitnexus-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.');
+                result.errors.push(`${label}: gitnexus-hook.cjs no longer contains the cliPath literal to patch — the installed hook may fail to resolve the CLI. Update CLI_PATH_SOURCE_LITERAL in setup.ts.`);
             }
             content = content.replace(CLI_PATH_SOURCE_LITERAL, `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
@@ -446,12 +452,12 @@ async function installClaudeCodeHooks(result) {
             await fs.access(dest);
         }
         catch {
-            result.errors.push('Claude Code hooks: adapter script was not installed — skipping hook registration');
+            result.errors.push(`${label}: adapter script was not installed — skipping hook registration`);
             return;
         }
-        const failedRequired = await copyHookHelpers(pluginHooksPath, destHooksDir, 'Claude Code hooks', result);
+        const failedRequired = await copyHookHelpers(pluginHooksPath, destHooksDir, label, result);
         if (failedRequired.length > 0) {
-            result.errors.push(`Claude Code hooks: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
+            result.errors.push(`${label}: required helper(s) ${failedRequired.join(', ')} failed to copy — skipping hook registration`);
             return;
         }
         const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
@@ -467,9 +473,10 @@ async function installClaudeCodeHooks(result) {
             }
         })();
         const hookEntries = [];
-        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
-        // Session context is delivered via CLAUDE.md / skills instead.
-        if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse', claudeHook.needle)) {
+        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576),
+        // and Codex reads AGENTS.md natively. Session context is delivered via
+        // CLAUDE.md / AGENTS.md / skills instead.
+        if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse', hookCfg.needle)) {
             hookEntries.push({
                 eventName: 'PreToolUse',
                 value: {
@@ -485,7 +492,7 @@ async function installClaudeCodeHooks(result) {
                 },
             });
         }
-        if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse', claudeHook.needle)) {
+        if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse', hookCfg.needle)) {
             hookEntries.push({
                 eventName: 'PostToolUse',
                 value: {
@@ -502,19 +509,19 @@ async function installClaudeCodeHooks(result) {
             });
         }
         if (hookEntries.length === 0) {
-            result.configured.push('Claude Code hooks (already configured)');
+            result.configured.push(`${label} (already configured)`);
             return;
         }
         const ok = await mergeHooksJsonc(settingsPath, hookEntries);
         if (ok) {
-            result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
+            result.configured.push(`${label} (PreToolUse, PostToolUse)`);
         }
         else {
-            result.errors.push('Claude Code hooks: settings.json is corrupt — skipping to preserve existing content');
+            result.errors.push(`${label}: ${path.basename(settingsPath)} is corrupt — skipping to preserve existing content`);
         }
     }
     catch (err) {
-        result.errors.push(`Claude Code hooks: ${err.message}`);
+        result.errors.push(`${label}: ${err.message}`);
     }
 }
 // ─── Antigravity (Google) ──────────────────────────────────────────
@@ -1053,7 +1060,7 @@ export const setupCommand = async (options) => {
     // Install global skills for platforms that support them
     if (selected.has('claude')) {
         await installClaudeCodeSkills(result);
-        await installClaudeCodeHooks(result);
+        await installClaudeSchemaHooks(result, 'claude');
     }
     if (selected.has('antigravity')) {
         await installAntigravitySkills(result);
@@ -1067,8 +1074,10 @@ export const setupCommand = async (options) => {
         await installCodeBuddySkills(result);
     if (selected.has('qoder'))
         await installQoderSkills(result);
-    if (selected.has('codex'))
+    if (selected.has('codex')) {
         await installCodexSkills(result);
+        await installClaudeSchemaHooks(result, 'codex');
+    }
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');