gitnexus 1.6.10-rc.1 → 1.6.10-rc.2

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):

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/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:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.1",
+  "version": "1.6.10-rc.2",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",