klypix-mcp 1.32.0 → 1.33.0

package/README.md

@@ -10,13 +10,21 @@ You've seen the setup: point an AI at a folder of notes, watch the graph fill up
 
 ## Quick start
 
-**Claude Code (native — live hooks, zero effort):**
+**Claude Code + Codex (native, machine-wide):**
 
 ```bash
 npx klypix-mcp install
 ```
 
-Every repo on your machine with a `brain.klypix` now auto-briefs each session with the project's state and auto-captures decisions as you work. Give a project a brain by dropping a `brain.klypix` in it — the [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or `create_canvas` makes one from any agent.
+Claude Code gets live hooks for auto-brief + auto-capture. Codex gets a native
+`~/.codex/config.toml` MCP registration and conditional global guidance that activates
+only when a project contains `./brain.klypix`. Existing MCP servers, Codex settings, and
+personal instructions are preserved and backed up before KLYPIX-owned blocks change.
+Restart Codex after installation so it loads the new server.
+
+Give a project a brain by dropping a `brain.klypix` in it — the
+[KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*),
+or `create_canvas` makes one from any agent.
 
 **Every other agent tool (one command per project):**
 
@@ -24,7 +32,9 @@ Every repo on your machine with a `brain.klypix` now auto-briefs each session wi
 npx klypix-mcp link
 ```
 
-Extends the brain to Cursor & VS Code/Copilot (MCP config + rules) and to Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent — always-on rules that teach the tool to read and capture the brain.
+Adds project-native config for Codex, Cursor, and VS Code/Copilot, plus rules for
+Cline, Windsurf, Gemini CLI, Aider, and any AGENTS.md-reading agent. Verify all
+managed files without changing them with `npx klypix-mcp link --check`.
 
 ## What a project brain does
 
@@ -86,11 +96,11 @@ Then ask your agent things like *"what did we decide about auth?"*, *"challenge
 
 ### Tools vs. the *automatic* brain
 
-This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), in any project. The **automatic** brain — auto-capturing decisions from your work, injecting the brief into each session, coordinating concurrent sessions (*push*) — runs in a host **hook**, which `npx klypix-mcp install` wires for Claude Code (and the [KLYPIX desktop app](https://klypix.com) ships built-in). Other tools get the always-on rules via `link`.
+This package is the **agent-neutral read/write surface** — any MCP client gets the tools above on demand (*pull*), in any project. `install` wires Claude Code's live hooks and Codex's native MCP + conditional global guidance; `link` projects the repository-level MCP and instruction files used by Codex and the other coding agents. Full transcript-driven auto-capture remains a Claude Code hook capability; Codex and other hookless clients capture durable decisions through the MCP instructions and `brain_note`.
 
 ### Updates — the propagation contract
 
-`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain`, and the emitted config runs the server **from that installed bundle** (no npx cache to go stale). Updates are then automatic: at session start the hook checks npm (≤ once/24h, fail-open, disable with `KLYPIX_AUTO_UPDATE=0`) and self-installs newer releases. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or `/mcp` reconnect); `brain_doctor`'s RUNNING line tells you when that's needed.
+`install` lays the whole brain (hooks + engine + local MCP server) into `~/.claude/project-brain`, then points both Claude and Codex at that installed bundle so there is no npx cache to go stale. Updates are automatic through the Claude session-start hook: it checks npm (≤ once/24h, fail-open, disable with `KLYPIX_AUTO_UPDATE=0`) and self-installs newer releases, including healing the Codex registration. One honest caveat: a running stdio server can't hot-swap — a new binary loads on the next full app launch (or `/mcp` reconnect); `brain_doctor`'s RUNNING line tells you when that's needed.
 
 ## Also speaks A2A (Agent-to-Agent)
 

package/bin/klypix-install.mjs

@@ -16,7 +16,11 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { mcpServerEntry } from '../src/agent-rules.mjs';
+import {
+    connectCodexMcpServer,
+    mcpServerEntry,
+    mergeCodexGlobalInstructions,
+} from '../src/agent-rules.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -29,6 +33,7 @@ const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
 const BRAIN_DIR = path.join(CLAUDE_DIR, 'project-brain');
 const SETTINGS = path.join(CLAUDE_DIR, 'settings.json');
+const CODEX_CONFIG = path.join(HOME, '.codex', 'config.toml');
 const HOOK_MARK = 'global-brain-hook';
 const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
 const fwd = (p) => p.replace(/\\/g, '/');
@@ -40,6 +45,28 @@ function copyDir(src, dest) {
     }
 }
 
+// Codex has two independent integration layers: MCP gives it the brain tools,
+// while a conditional managed block in ~/.codex/AGENTS.md tells every session
+// to use those tools when ./brain.klypix exists.
+function wireCodex() {
+    const mcp = connectCodexMcpServer({
+        configPath: CODEX_CONFIG,
+        entry: mcpServerEntry({ vault: '.', home: HOME }),
+    });
+    const instructions = mergeCodexGlobalInstructions(HOME);
+    return { mcp, instructions, ok: mcp.ok && instructions.ok };
+}
+
+function reportCodex(result) {
+    if (result.ok) {
+        console.log(`✓ wired Codex: MCP tools (${result.mcp.action}) + conditional project-brain guidance (${result.instructions.action})`);
+        return;
+    }
+    if (!result.mcp.ok) console.error(`⚠ Codex MCP was not changed: ${result.mcp.error}`);
+    if (!result.instructions.ok) console.error(`⚠ Codex guidance was not changed: ${result.instructions.error}`);
+    console.error('  Claude Code installation is intact. Fix the Codex warning, then re-run this command.');
+}
+
 // ── Never-downgrade gate ─────────────────────────────────────────────────────
 // The brain version is a UNIFIED namespace = the klypix-mcp version, stamped by BOTH
 // the npm install (here) and the desktop bundle, so the two channels compare cleanly.
@@ -48,8 +75,16 @@ function copyDir(src, dest) {
 const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
 const cur = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.brain-version.json'), 'utf8')); } catch { return null; } })();
 if (!FORCE && cur) {
-    if (cur.dev === true) { console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`); process.exit(0); }
-    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) { console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`); process.exit(0); }
+    if (cur.dev === true) {
+        console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`);
+        reportCodex(wireCodex());
+        process.exit(0);
+    }
+    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) {
+        console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`);
+        reportCodex(wireCodex());
+        process.exit(0);
+    }
 }
 
 // ── Install lock (auto-propagation, part D — concurrency) ─────────────────────
@@ -218,6 +253,9 @@ try {
     //    (heals an existing stale config so the next MCP server spawn runs current).
     const migrated = migrateProjectMcpConfig();
 
+    // Codex needs both native MCP tools and conditional global guidance.
+    const codex = wireCodex();
+
     // 8) READINESS check — re-read what we just wrote and confirm all 4 hooks actually
     //    took (a malformed pre-existing group, a partial merge, or a later hand-edit can
     //    leave the brain LIVE but not LEARNING — liveness ≠ readiness). Warn, don't fail.
@@ -226,12 +264,13 @@ try {
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
 
     if (gotLock) releaseLock();
+    reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
     if (!notWired.length) console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);
     console.log(`✓ MCP server runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — no npx cache, works offline, always the installed version.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);
-    console.log('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions.');
+    console.log('  Claude Code auto-briefs + captures through hooks; Codex reads + writes through native MCP and managed guidance.');
     console.log('  ⚠ Open sessions keep their OLD server until relaunched: fully quit & reopen the app (a session resume / new chat does NOT respawn the MCP server). `brain_doctor`\'s RUNNING line confirms when you\'re current.');
     console.log('  Verify anytime: `npx klypix-mcp doctor` (is the brain current + wired + in sync, who else is live).');
 } catch (e) {

package/bin/klypix-link.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // klypix-link — make THIS project's brain automatic for EVERY agent tool.
-// `npx klypix-mcp install` gives Claude Code the brain via hooks; `link` extends the
-// same automatic read+capture to Cursor, Cline, Windsurf, Copilot/VS Code, Gemini CLI,
-// Aider, and any AGENTS.md-reading agent, by dropping each tool's native MCP config +
+// `npx klypix-mcp install` gives Claude Code hooks and wires Codex globally; `link`
+// extends the same automatic read+capture per project to Codex, Cursor, Cline,
+// Windsurf, Copilot/VS Code, Gemini CLI, Aider, and any AGENTS.md-reading agent,
+// by dropping each tool's native MCP config +
 // rules file in the current project. Idempotent — re-run anytime to refresh. The managed
 // block carries the brain version + a content hash, so:
 //
@@ -48,7 +49,7 @@ try {
 
   const changed = [...rules, ...mcp].filter(r => r.action && !['unchanged', 'skipped'].includes(r.action)).length;
   console.log(`\n✓ ${changed} file(s) written/updated — every agent opened in this project now reads + captures ./brain.klypix.`);
-  console.log('  Cline & Windsurf MCP servers live in their global config; the rules file points them at the brain regardless.');
+  console.log('  Codex gets .codex/config.toml + AGENTS.md; Cline & Windsurf use their global MCP config plus project rules.');
   console.log('  Verify anytime with `npx klypix-mcp link --check` (or `npx klypix-mcp doctor`).');
   if (!hasBrain) {
     console.log('\n⚠ No ./brain.klypix here yet — the rules reference it for when you create one.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "klypix-mcp",
-  "version": "1.32.0",
-  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Cursor, Cline, any model.",
+  "version": "1.33.0",
+  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Codex, Cursor, Cline, any model.",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [

package/src/agent-rules.mjs

@@ -49,6 +49,304 @@ export function mcpServerEntry({ vault = '.', withType = false, home } = {}) {
   if (!base) base = { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', vault] };
   return withType ? { type: 'stdio', ...base } : base;
 }
+
+// Codex uses TOML rather than the JSON MCP shape used by the other clients.
+// These helpers replace only KLYPIX-owned table sections, preserving comments,
+// formatting, and every unrelated setting byte-for-byte. They intentionally do
+// not serialize the whole document.
+const CODEX_GLOBAL_START = '<!-- klypix-codex:start (managed by klypix-mcp) -->';
+const CODEX_GLOBAL_END = '<!-- klypix-codex:end -->';
+const CODEX_GLOBAL_RE = /<!-- klypix-codex:start \(managed by klypix-mcp\) -->[\s\S]*?<!-- klypix-codex:end -->\r?\n?/;
+const CODEX_GLOBAL_BODY = [
+  CODEX_GLOBAL_START,
+  '## KLYPIX project brains',
+  '',
+  'When the current project contains `./brain.klypix`, treat it as the authoritative shared project memory.',
+  'At task start, read `.claude/brain-brief.md` when present; otherwise use the `klypix-canvas`',
+  'MCP tools (`brain_ask`, `read_canvas` with canvas `"brain"`, or `brain_insights`).',
+  'Capture durable decisions and milestones with `brain_note`. Never hand-edit `brain.klypix`.',
+  'If the project has no `brain.klypix`, ignore this section.',
+  CODEX_GLOBAL_END,
+].join('\n');
+
+const tomlKey = (value) => /^[A-Za-z0-9_-]+$/.test(String(value)) ? String(value) : JSON.stringify(String(value));
+const tomlString = (value) => JSON.stringify(String(value));
+const eolOf = (raw) => raw.includes('\r\n') ? '\r\n' : '\n';
+
+function parseTomlDottedKey(source) {
+  const out = [];
+  let token = '';
+  let quote = null;
+  let escaped = false;
+  const push = () => {
+    const s = token.trim();
+    token = '';
+    if (!s) return false;
+    if (s.startsWith('"')) {
+      try { out.push(JSON.parse(s)); } catch { return false; }
+    } else if (s.startsWith("'")) {
+      if (s.length < 2 || !s.endsWith("'")) return false;
+      out.push(s.slice(1, -1));
+    } else {
+      if (!/^[A-Za-z0-9_-]+$/.test(s)) return false;
+      out.push(s);
+    }
+    return true;
+  };
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (quote === '"') {
+      token += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') quote = null;
+      continue;
+    }
+    if (quote === "'") {
+      token += ch;
+      if (ch === "'") quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; token += ch; continue; }
+    if (ch === '.') { if (!push()) return null; continue; }
+    token += ch;
+  }
+  if (quote || !push()) return null;
+  return out;
+}
+
+function scanTomlMultiline(line, initial) {
+  let state = initial;
+  let i = 0;
+  while (i < line.length) {
+    if (state) {
+      let at = line.indexOf(state, i);
+      while (state === '"""' && at >= 0) {
+        let slashes = 0;
+        for (let j = at - 1; j >= 0 && line[j] === '\\'; j--) slashes++;
+        if (slashes % 2 === 0) break;
+        at = line.indexOf(state, at + 3);
+      }
+      if (at < 0) return state;
+      state = null;
+      i = at + 3;
+      continue;
+    }
+    const ch = line[i];
+    if (ch === '#') break;
+    const tri = line.slice(i, i + 3);
+    if (tri === '"""' || tri === "'''") { state = tri; i += 3; continue; }
+    if (ch === '"') {
+      i++;
+      let escaped = false;
+      while (i < line.length) {
+        const c = line[i++];
+        if (escaped) escaped = false;
+        else if (c === '\\') escaped = true;
+        else if (c === '"') break;
+      }
+      continue;
+    }
+    if (ch === "'") {
+      const close = line.indexOf("'", i + 1);
+      i = close < 0 ? line.length : close + 1;
+      continue;
+    }
+    i++;
+  }
+  return state;
+}
+
+function scanTomlTables(raw) {
+  const tables = [];
+  const lines = raw.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g) || [];
+  let offset = 0;
+  let multiline = null;
+  for (const fullLine of lines) {
+    if (!fullLine) continue;
+    const line = fullLine.replace(/(?:\r\n|\n|\r)$/, '').replace(/^\uFEFF/, '');
+    if (!multiline) {
+      const array = line.match(/^[ \t]*\[\[(.+)\]\][ \t]*(?:#.*)?$/);
+      const table = array ? null : line.match(/^[ \t]*\[([^\[\]].*)\][ \t]*(?:#.*)?$/);
+      const match = array || table;
+      if (match) {
+        const parts = parseTomlDottedKey(match[1].trim());
+        if (!parts) return { ok: false, error: 'contains a table header KLYPIX cannot safely parse', tables: [] };
+        tables.push({ start: offset, end: raw.length, parts, array: !!array });
+      }
+    }
+    multiline = scanTomlMultiline(line, multiline);
+    offset += fullLine.length;
+  }
+  if (multiline) return { ok: false, error: 'contains an unterminated multiline TOML string', tables: [] };
+  for (let i = 0; i < tables.length - 1; i++) tables[i].end = tables[i + 1].start;
+  return { ok: true, tables };
+}
+
+function parseTomlStringValue(rawValue) {
+  const value = rawValue.trim();
+  if (value.startsWith('"')) {
+    const m = value.match(/^"((?:\\.|[^"])*)"/);
+    if (!m) return null;
+    try { return JSON.parse(`"${m[1]}"`); } catch { return null; }
+  }
+  const m = value.match(/^'([^']*)'/);
+  return m ? m[1] : null;
+}
+
+export function safeReadCodexConfig(configPath) {
+  if (!exists(configPath)) return { ok: true, raw: '', servers: {} };
+  let raw;
+  try { raw = fs.readFileSync(configPath, 'utf8'); }
+  catch (e) { return { ok: false, raw: '', servers: {}, error: `Can't read ${configPath}: ${e?.message || e}` }; }
+  const scanned = scanTomlTables(raw);
+  if (!scanned.ok) {
+    return { ok: false, raw, servers: {}, error: `${path.basename(configPath)} ${scanned.error}. Fix it first - KLYPIX left it untouched.` };
+  }
+  const servers = {};
+  for (const table of scanned.tables) {
+    if (table.array || table.parts[0] !== 'mcp_servers' || table.parts.length < 2) continue;
+    const name = String(table.parts[1]);
+    if (servers[name]) continue; // nested .env/.tools table for an existing server
+    const block = raw.slice(table.start, table.end);
+    const commandLine = block.match(/^[ \t]*command[ \t]*=[ \t]*(.+)$/m);
+    const command = commandLine ? parseTomlStringValue(commandLine[1]) : null;
+    const launchesKlypix = /(?:klypix-mcp-server\.mjs|(?:^|["'\s,])klypix-mcp(?:["'\s,]|$))/i.test(block)
+      && !!command && /(?:^|[\\/])(node|node\.exe|npx|npx\.cmd|cmd|cmd\.exe)$/i.test(command);
+    servers[name] = { command, launchesKlypix, raw: block };
+  }
+  return { ok: true, raw, servers, tables: scanned.tables };
+}
+
+function renderCodexMcpTable(name, entry, cwd) {
+  const args = Array.isArray(entry?.args) ? entry.args.map(tomlString).join(', ') : '';
+  const lines = [
+    `[mcp_servers.${tomlKey(name)}]`,
+    `command = ${tomlString(entry?.command || 'npx')}`,
+    `args = [${args}]`,
+  ];
+  if (cwd) lines.push(`cwd = ${tomlString(cwd)}`);
+  // A cold npx bootstrap can exceed Codex's 10 second default; local installs
+  // start immediately, but the larger timeout is harmless and makes first use reliable.
+  lines.push('startup_timeout_sec = 120');
+  return lines.join('\n');
+}
+
+function writeCodexConfig(configPath, raw, next) {
+  try {
+    ensureDir(configPath);
+    let backup;
+    if (raw) {
+      backup = configPath + '.klypix-bak';
+      try { fs.writeFileSync(backup, raw, 'utf8'); } catch { backup = undefined; }
+    }
+    const tmp = configPath + '.klypix-tmp';
+    fs.writeFileSync(tmp, next, 'utf8');
+    const verify = safeReadCodexConfig(tmp);
+    if (!verify.ok) { try { fs.unlinkSync(tmp); } catch { /* best effort */ } return { ok: false, error: verify.error }; }
+    fs.renameSync(tmp, configPath);
+    return { ok: true, backup };
+  } catch (e) {
+    return { ok: false, error: `Couldn't write ${configPath}: ${e?.message || e}` };
+  }
+}
+
+export function connectCodexMcpServer({ configPath, name = 'klypix-canvas', entry, cwd } = {}) {
+  const parsed = safeReadCodexConfig(configPath);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const existingNames = Object.keys(parsed.servers).filter(k => /klypix/i.test(k));
+  const chosen = existingNames[0] || name;
+  const owned = (parsed.tables || []).filter(t => t.parts[0] === 'mcp_servers' && t.parts.length >= 2 && /klypix/i.test(String(t.parts[1])));
+  const eol = eolOf(parsed.raw);
+  const block = renderCodexMcpTable(chosen, entry, cwd).replace(/\n/g, eol);
+  let next = parsed.raw;
+  if (owned.length) {
+    const firstStart = owned[0].start;
+    for (const table of [...owned].sort((a, b) => b.start - a.start)) {
+      next = next.slice(0, table.start) + (table.start === firstStart ? block + eol + eol : '') + next.slice(table.end);
+    }
+  } else {
+    const needsEol = next.length > 0 && !/[\r\n]$/.test(next);
+    const spacer = next.trim() ? eol : '';
+    next += (needsEol ? eol : '') + spacer + block + eol + eol;
+  }
+  if (next === parsed.raw) {
+    return { ok: true, action: 'unchanged', name: chosen, path: configPath, otherServers: Object.keys(parsed.servers).filter(k => !/klypix/i.test(k)) };
+  }
+  const written = writeCodexConfig(configPath, parsed.raw, next);
+  if (!written.ok) return written;
+  return {
+    ok: true,
+    action: existingNames.length ? 'updated' : 'connected',
+    name: chosen,
+    path: configPath,
+    backup: written.backup,
+    otherServers: Object.keys(parsed.servers).filter(k => !/klypix/i.test(k)),
+  };
+}
+
+export function disconnectCodexMcpServer({ configPath } = {}) {
+  const parsed = safeReadCodexConfig(configPath);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  const owned = (parsed.tables || []).filter(t => t.parts[0] === 'mcp_servers' && t.parts.length >= 2 && /klypix/i.test(String(t.parts[1])));
+  if (!owned.length) return { ok: true, action: 'unchanged', path: configPath };
+  let next = parsed.raw;
+  for (const table of [...owned].sort((a, b) => b.start - a.start)) {
+    next = next.slice(0, table.start) + next.slice(table.end);
+  }
+  const written = writeCodexConfig(configPath, parsed.raw, next);
+  if (!written.ok) return written;
+  return {
+    ok: true,
+    action: 'disconnected',
+    path: configPath,
+    backup: written.backup,
+    otherServers: Object.keys(parsed.servers).filter(k => !/klypix/i.test(k)),
+  };
+}
+
+export function mergeCodexGlobalInstructions(home = os.homedir()) {
+  const file = path.join(home, '.codex', 'AGENTS.md');
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { /* fresh file */ }
+  const eol = eolOf(raw);
+  const block = CODEX_GLOBAL_BODY.replace(/\n/g, eol);
+  const next = CODEX_GLOBAL_RE.test(raw)
+    ? raw.replace(CODEX_GLOBAL_RE, block + eol)
+    : (raw.trim() ? raw.replace(/\s*$/, '') + eol + eol + block + eol : block + eol);
+  if (next === raw) return { ok: true, action: 'unchanged', path: file };
+  try {
+    ensureDir(file);
+    let backup;
+    if (raw) { backup = file + '.klypix-bak'; try { fs.writeFileSync(backup, raw, 'utf8'); } catch { backup = undefined; } }
+    const tmp = file + '.klypix-tmp';
+    fs.writeFileSync(tmp, next, 'utf8');
+    fs.renameSync(tmp, file);
+    return { ok: true, action: CODEX_GLOBAL_RE.test(raw) ? 'updated' : 'connected', path: file, backup };
+  } catch (e) { return { ok: false, error: `Couldn't write ${file}: ${e?.message || e}` }; }
+}
+
+export function removeCodexGlobalInstructions(home = os.homedir()) {
+  const file = path.join(home, '.codex', 'AGENTS.md');
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { ok: true, action: 'unchanged', path: file }; }
+  if (!CODEX_GLOBAL_RE.test(raw)) return { ok: true, action: 'unchanged', path: file };
+  const next = raw.replace(CODEX_GLOBAL_RE, '').replace(/^\s+|\s+$/g, (m, offset) => offset === 0 ? '' : '\n');
+  try {
+    const backup = file + '.klypix-bak';
+    try { fs.writeFileSync(backup, raw, 'utf8'); } catch { /* best effort */ }
+    const tmp = file + '.klypix-tmp';
+    fs.writeFileSync(tmp, next, 'utf8');
+    fs.renameSync(tmp, file);
+    return { ok: true, action: 'disconnected', path: file, backup };
+  } catch (e) { return { ok: false, error: `Couldn't write ${file}: ${e?.message || e}` }; }
+}
+
+export function codexGlobalInstructionsInstalled(home = os.homedir()) {
+  try { return CODEX_GLOBAL_RE.test(fs.readFileSync(path.join(home, '.codex', 'AGENTS.md'), 'utf8')); }
+  catch { return false; }
+}
+
 const sha8 = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 8);
 const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
 
@@ -253,7 +551,7 @@ function targets(projectDir) {
   const j = (...p) => path.join(projectDir, ...p);
   return {
     rules: [
-      { tool: 'AGENTS.md (cross-tool standard)', file: j('AGENTS.md'), kind: 'merge' },
+      { tool: 'Codex / AGENTS.md standard', file: j('AGENTS.md'), kind: 'merge' },
       { tool: 'Cursor', file: j('.cursor', 'rules', 'klypix-brain.mdc'), kind: 'dedicated', frontmatter: '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---' },
       { tool: 'Windsurf', file: j('.windsurf', 'rules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '---\ntrigger: always_on\n---' },
       { tool: 'Cline', file: j('.clinerules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '' },
@@ -267,6 +565,7 @@ function targets(projectDir) {
       { tool: 'Antigravity', file: j('.agents', 'AGENTS.md'), kind: 'merge' },
     ],
     mcp: [
+      { tool: 'Codex', file: j('.codex', 'config.toml'), format: 'toml' },
       { tool: 'Cursor', file: j('.cursor', 'mcp.json'), wrapKey: 'mcpServers', withType: false },
       { tool: 'VS Code (Copilot/Continue)', file: j('.vscode', 'mcp.json'), wrapKey: 'servers', withType: true },
     ],
@@ -299,6 +598,20 @@ export function linkProject(projectDir, opts = {}) {
   // MCP), so we skip .mcp.json to avoid double-registering its server.
   const mcp = t.mcp.map((m) => {
     const file = relFile(projectDir, m.file);
+    if (m.format === 'toml') {
+      if (check) {
+        const parsed = safeReadCodexConfig(m.file);
+        if (!parsed.ok) return { tool: m.tool, file, status: 'hand-edited', why: parsed.error };
+        const name = Object.keys(parsed.servers).find(k => /klypix/i.test(k));
+        const entry = name ? parsed.servers[name] : null;
+        return { tool: m.tool, file, status: entry ? (entry.launchesKlypix ? 'ok' : 'hand-edited') : 'missing', why: entry && !entry.launchesKlypix ? 'entry no longer launches klypix-mcp' : undefined };
+      }
+      // Project config is commonly committed. Keep it machine-portable; the
+      // 120s Codex startup timeout covers the one-time npx bootstrap.
+      const portableEntry = { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', '.'] };
+      const res = connectCodexMcpServer({ configPath: m.file, entry: portableEntry, cwd: '..' });
+      return res.ok ? { tool: m.tool, file, ...res } : { tool: m.tool, file, action: 'skipped', why: res.error };
+    }
     if (check) return { tool: m.tool, file, ...classifyMcp(m.file, m.wrapKey) };
     return { tool: m.tool, file, ...mergeMcpJson(m.file, m.wrapKey, m.withType) };
   });