feat: add Codex MCP and skills support

README.md

@@ -17,7 +17,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 > *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
 
-**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
+**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
 
 ---
 
@@ -31,7 +31,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 |                   | **CLI + MCP**                                            | **Web UI**                                             |
 | ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
 | **What**    | Index repos locally, connect AI agents via MCP                 | Visual graph explorer + AI chat in browser                   |
-| **For**     | Daily development with Cursor, Claude Code, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
+| **For**     | Daily development with Cursor, Claude Code, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
 | **Scale**   | Full repos, any size                                           | Limited by browser memory (~5k files), or unlimited via backend mode |
 | **Install** | `npm install -g gitnexus`                                    | No install —[gitnexus.vercel.app](https://gitnexus.vercel.app) |
 | **Storage** | KuzuDB native (fast, persistent)                               | KuzuDB WASM (in-memory, per session)                         |
@@ -67,6 +67,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   |
 
@@ -86,6 +87,12 @@ If you prefer manual configuration:
 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** (`~/.cursor/mcp.json` — global, works for all projects):
 
 ```json
@@ -247,7 +254,7 @@ The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAs
 
 ## The Problem GitNexus Solves
 
-Tools like **Cursor**, **Claude Code**, **Cline**, **Roo Code**, and **Windsurf** are powerful — but they don't truly know your codebase structure.
+Tools like **Cursor**, **Claude Code**, **Codex**, **Cline**, **Roo Code**, and **Windsurf** are powerful — but they don't truly know your codebase structure.
 
 **What happens:**
 

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

gitnexus/package.json

@@ -20,6 +20,7 @@
     "knowledge-graph",
     "cursor",
     "claude",
+    "codex",
     "ai-agent",
     "gitnexus",
     "static-analysis",

gitnexus/src/cli/ai-context.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.
  */
 
@@ -250,4 +250,3 @@ export async function generateAIContextFiles(
 
   return { files: createdFiles };
 }
-

gitnexus/src/cli/index.ts

@@ -20,7 +20,7 @@ program
 
 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(setupCommand);
 
 program

gitnexus/src/cli/setup.ts

@@ -9,11 +9,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 { getGlobalDir } from '../storage/repo-manager.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const execFileAsync = promisify(execFile);
 
 interface SetupResult {
   configured: string[];
@@ -222,6 +225,65 @@ async function setupOpenCode(result: SetupResult): Promise<void> {
   }
 }
 
+/**
+ * Build a TOML section for Codex MCP config (~/.codex/config.toml).
+ */
+function getCodexMcpTomlSection(): string {
+  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: string): Promise<void> {
+  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: SetupResult): Promise<void> {
+  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]);
+    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: any) {
+    result.errors.push(`Codex: ${err.message}`);
+  }
+}
+
 // ─── Skill Installation ───────────────────────────────────────────
 
 const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring'];
@@ -229,7 +291,7 @@ const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring']
 /**
  * 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
@@ -325,6 +387,24 @@ async function installOpenCodeSkills(result: SetupResult): Promise<void> {
   }
 }
 
+/**
+ * Install global Codex skills to ~/.agents/skills/gitnexus/
+ */
+async function installCodexSkills(result: SetupResult): Promise<void> {
+  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: any) {
+    result.errors.push(`Codex skills: ${err.message}`);
+  }
+}
+
 // ─── Main command ──────────────────────────────────────────────────
 
 export const setupCommand = async () => {
@@ -347,12 +427,14 @@ 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) {