@jmylchreest/aide-plugin 0.0.57 → 0.0.59

package/src/cli/install.ts

@@ -1,5 +1,5 @@
 /**
- * Install command — registers aide plugin and MCP server in OpenCode config.
+ * Install command — registers aide plugin and MCP server for OpenCode or Codex CLI.
  *
  * On reinstall, detects and upgrades stale MCP command configurations
  * (e.g. old `aide-wrapper` commands) to the current format.
@@ -15,51 +15,37 @@ import {
   PLUGIN_NAME,
   MCP_SERVER_NAME,
 } from "./config.js";
+import { installCodex, isCodexConfigured } from "./codex-config.js";
 
 export interface InstallFlags {
   project?: boolean;
   noMcp?: boolean;
+  platform?: "opencode" | "codex";
 }
 
-/**
- * Check if an existing MCP config has the current expected command format.
- * Returns false if the command is missing, empty, or uses an outdated format.
- */
 function isMcpCommandCurrent(config: ReturnType<typeof readConfig>): boolean {
   const mcpConfig = config.mcp?.[MCP_SERVER_NAME];
-  if (!mcpConfig?.command || mcpConfig.command.length === 0) {
-    return false;
-  }
-
+  if (!mcpConfig?.command || mcpConfig.command.length === 0) return false;
   const cmd = mcpConfig.command;
-
-  // Current format: ["bunx", "-y", "@jmylchreest/aide-plugin", "mcp"]
-  if (
+  return (
     cmd.length === 4 &&
     cmd[0] === "bunx" &&
     cmd[1] === "-y" &&
     cmd[2] === PLUGIN_NAME &&
     cmd[3] === "mcp"
-  ) {
-    return true;
-  }
-
-  return false;
+  );
 }
 
-export async function install(flags: InstallFlags): Promise<void> {
+async function installOpenCode(flags: InstallFlags): Promise<void> {
   const configPath = flags.project
     ? getProjectConfigPath()
     : getGlobalConfigPath();
 
   const scope = flags.project ? "project" : "global";
-  console.log(`Installing aide plugin (${scope})...\n`);
+  console.log(`Installing aide plugin for OpenCode (${scope})...\n`);
 
-  // Read existing config
   const existing = readConfig(configPath);
   const before = isAideConfigured(existing);
-
-  // Check if MCP command needs updating (stale format from older versions)
   const mcpNeedsUpdate =
     !flags.noMcp && before.mcp && !isMcpCommandCurrent(existing);
 
@@ -71,16 +57,13 @@ export async function install(flags: InstallFlags): Promise<void> {
     return;
   }
 
-  // If MCP config is stale, remove it so addAideToConfig will write the current version
   if (mcpNeedsUpdate && existing.mcp) {
     delete existing.mcp[MCP_SERVER_NAME];
   }
 
-  // Apply changes
   const updated = addAideToConfig(existing, { noMcp: flags.noMcp });
   writeConfig(configPath, updated);
 
-  // Report what was done
   const after = isAideConfigured(updated);
   console.log(`Updated: ${configPath}\n`);
 
@@ -110,3 +93,47 @@ export async function install(flags: InstallFlags): Promise<void> {
     );
   }
 }
+
+async function installForCodex(flags: InstallFlags): Promise<void> {
+  const scope = flags.project ? "project" : "user";
+  console.log(`Installing aide for Codex CLI (${scope})...\n`);
+
+  const before = isCodexConfigured(scope);
+  if (before.mcp && before.hooks) {
+    console.log("aide is already configured for Codex CLI");
+    console.log("  mcp:   registered in config.toml");
+    console.log("  hooks: registered in hooks.json");
+    console.log("\nNothing to do.");
+    return;
+  }
+
+  const result = installCodex(scope);
+
+  if (result.configWritten) {
+    console.log("  + Added aide MCP server to config.toml");
+  } else if (before.mcp) {
+    console.log("  = MCP server already registered in config.toml");
+  }
+
+  if (result.hooksWritten) {
+    console.log("  + Generated hooks.json with aide hooks");
+  } else if (before.hooks) {
+    console.log("  = Hooks already registered in hooks.json");
+  }
+
+  console.log("\nInstallation complete. Start Codex CLI to use aide.");
+
+  if (!flags.project) {
+    console.log(
+      "\nThe plugin is installed globally and will apply to all Codex CLI sessions.",
+    );
+  }
+}
+
+export async function install(flags: InstallFlags): Promise<void> {
+  if (flags.platform === "codex") {
+    await installForCodex(flags);
+  } else {
+    await installOpenCode(flags);
+  }
+}

package/src/cli/status.ts

@@ -1,5 +1,5 @@
 /**
- * Status command — shows current aide installation status for OpenCode.
+ * Status command — shows current aide installation status for OpenCode or Codex CLI.
  */
 
 import { existsSync } from "fs";
@@ -9,38 +9,71 @@ import {
   isAideConfigured,
   readConfig,
 } from "./config.js";
+import {
+  isCodexConfigured,
+  getCodexConfigTomlPath,
+  getCodexHooksJsonPath,
+} from "./codex-config.js";
+
+export interface StatusFlags {
+  platform?: "opencode" | "codex";
+}
 
-export async function status(): Promise<void> {
-  console.log("aide plugin status\n");
+function showOpenCodeStatus(): void {
+  console.log("aide plugin status (OpenCode)\n");
 
   const globalPath = getGlobalConfigPath();
   const projectPath = getProjectConfigPath();
 
-  // Global config
   console.log(`Global config: ${globalPath}`);
   if (existsSync(globalPath)) {
-    const globalConfig = readConfig(globalPath);
-    const globalStatus = isAideConfigured(globalConfig);
-    console.log(
-      `  plugin: ${globalStatus.plugin ? "registered" : "not found"}`,
-    );
-    console.log(`  mcp:    ${globalStatus.mcp ? "registered" : "not found"}`);
+    const s = isAideConfigured(readConfig(globalPath));
+    console.log(`  plugin: ${s.plugin ? "registered" : "not found"}`);
+    console.log(`  mcp:    ${s.mcp ? "registered" : "not found"}`);
   } else {
     console.log("  (file does not exist)");
   }
 
   console.log();
 
-  // Project config
   console.log(`Project config: ${projectPath}`);
   if (existsSync(projectPath)) {
-    const projectConfig = readConfig(projectPath);
-    const projectStatus = isAideConfigured(projectConfig);
-    console.log(
-      `  plugin: ${projectStatus.plugin ? "registered" : "not found"}`,
-    );
-    console.log(`  mcp:    ${projectStatus.mcp ? "registered" : "not found"}`);
+    const s = isAideConfigured(readConfig(projectPath));
+    console.log(`  plugin: ${s.plugin ? "registered" : "not found"}`);
+    console.log(`  mcp:    ${s.mcp ? "registered" : "not found"}`);
   } else {
     console.log("  (file does not exist)");
   }
 }
+
+function showCodexStatus(): void {
+  console.log("aide plugin status (Codex CLI)\n");
+
+  const userConfig = getCodexConfigTomlPath("user");
+  const userHooks = getCodexHooksJsonPath("user");
+  const userStatus = isCodexConfigured("user");
+
+  console.log(`User config:  ${userConfig}`);
+  console.log(`User hooks:   ${userHooks}`);
+  console.log(`  mcp:   ${userStatus.mcp ? "registered" : "not found"}`);
+  console.log(`  hooks: ${userStatus.hooks ? "registered" : "not found"}`);
+
+  console.log();
+
+  const projectConfig = getCodexConfigTomlPath("project");
+  const projectHooks = getCodexHooksJsonPath("project");
+  const projectStatus = isCodexConfigured("project");
+
+  console.log(`Project config: ${projectConfig}`);
+  console.log(`Project hooks:  ${projectHooks}`);
+  console.log(`  mcp:   ${projectStatus.mcp ? "registered" : "not found"}`);
+  console.log(`  hooks: ${projectStatus.hooks ? "registered" : "not found"}`);
+}
+
+export async function status(flags?: StatusFlags): Promise<void> {
+  if (flags?.platform === "codex") {
+    showCodexStatus();
+  } else {
+    showOpenCodeStatus();
+  }
+}

package/src/cli/uninstall.ts

@@ -1,5 +1,5 @@
 /**
- * Uninstall command — removes aide plugin and MCP server from OpenCode config.
+ * Uninstall command — removes aide plugin and MCP server from OpenCode or Codex CLI config.
  */
 
 import {
@@ -10,18 +10,20 @@ import {
   removeAideFromConfig,
   writeConfig,
 } from "./config.js";
+import { uninstallCodex, isCodexConfigured } from "./codex-config.js";
 
 export interface UninstallFlags {
   project?: boolean;
+  platform?: "opencode" | "codex";
 }
 
-export async function uninstall(flags: UninstallFlags): Promise<void> {
+async function uninstallOpenCode(flags: UninstallFlags): Promise<void> {
   const configPath = flags.project
     ? getProjectConfigPath()
     : getGlobalConfigPath();
 
   const scope = flags.project ? "project" : "global";
-  console.log(`Uninstalling aide plugin (${scope})...\n`);
+  console.log(`Uninstalling aide plugin from OpenCode (${scope})...\n`);
 
   const existing = readConfig(configPath);
   const before = isAideConfigured(existing);
@@ -36,13 +38,32 @@ export async function uninstall(flags: UninstallFlags): Promise<void> {
   writeConfig(configPath, updated);
 
   console.log(`Updated: ${configPath}\n`);
+  if (before.plugin) console.log(`  - Removed aide plugin from plugin array`);
+  if (before.mcp) console.log(`  - Removed aide MCP server`);
+  console.log("\nUninstallation complete.");
+}
 
-  if (before.plugin) {
-    console.log(`  - Removed aide plugin from plugin array`);
-  }
-  if (before.mcp) {
-    console.log(`  - Removed aide MCP server`);
+async function uninstallFromCodex(flags: UninstallFlags): Promise<void> {
+  const scope = flags.project ? "project" : "user";
+  console.log(`Uninstalling aide from Codex CLI (${scope})...\n`);
+
+  const before = isCodexConfigured(scope);
+  if (!before.mcp && !before.hooks) {
+    console.log("aide is not configured for Codex CLI.");
+    console.log("\nNothing to do.");
+    return;
   }
 
+  const result = uninstallCodex(scope);
+  if (result.configRemoved) console.log("  - Removed aide MCP server from config.toml");
+  if (result.hooksRemoved) console.log("  - Removed aide hooks from hooks.json");
   console.log("\nUninstallation complete.");
 }
+
+export async function uninstall(flags: UninstallFlags): Promise<void> {
+  if (flags.platform === "codex") {
+    await uninstallFromCodex(flags);
+  } else {
+    await uninstallOpenCode(flags);
+  }
+}

package/src/core/mcp-sync.ts

@@ -8,6 +8,7 @@
  * Supports:
  *   - Claude Code: ~/.claude.json (user), .mcp.json (project) (reads legacy ~/.mcp.json)
  *   - OpenCode:    ~/.config/opencode/opencode.json (user), ./opencode.json (project)
+ *   - Codex CLI:   ~/.codex/config.toml (user), .codex/config.toml (project)
  *   - Aide canonical: ~/.aide/config/mcp.json (user), .aide/config/mcp.json (project)
  *
  * Uses a journal to detect intentional deletions from the aide canonical file,
@@ -21,17 +22,17 @@ import {
   writeFileSync,
   mkdirSync,
   statSync,
-  unlinkSync,
 } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
+import * as TOML from "smol-toml";
 
 // =============================================================================
 // Types
 // =============================================================================
 
 /** Platform identifier for the current assistant. */
-export type McpPlatform = "claude-code" | "opencode";
+export type McpPlatform = "claude-code" | "opencode" | "codex";
 
 /**
  * Discover MCP server names managed by installed Claude Code plugins.
@@ -204,6 +205,11 @@ function getAssistantReadPaths(
       ? [join(homedir(), ".config", "opencode", "opencode.json")]
       : [join(cwd, "opencode.json")];
   }
+  if (platform === "codex") {
+    return scope === "user"
+      ? [join(homedir(), ".codex", "config.toml")]
+      : [join(cwd, ".codex", "config.toml")];
+  }
   return [];
 }
 
@@ -222,6 +228,11 @@ function getAssistantWritePaths(
       ? [join(homedir(), ".config", "opencode", "opencode.json")]
       : [join(cwd, "opencode.json")];
   }
+  if (platform === "codex") {
+    return scope === "user"
+      ? [join(homedir(), ".codex", "config.toml")]
+      : [join(cwd, ".codex", "config.toml")];
+  }
   return [];
 }
 
@@ -369,6 +380,59 @@ function readOpenCodeConfig(path: string): Record<string, CanonicalMcpServer> {
   }
 }
 
+/**
+ * Read Codex CLI MCP config from config.toml.
+ *
+ * Format:
+ * ```toml
+ * [mcp_servers.name]
+ * command = "npx"
+ * args = ["package-name"]
+ *
+ * [mcp_servers.name.env]
+ * KEY = "value"
+ * ```
+ */
+function readCodexConfig(path: string): Record<string, CanonicalMcpServer> {
+  if (!existsSync(path)) return {};
+
+  try {
+    const raw = TOML.parse(readFileSync(path, "utf-8"));
+    const servers: Record<string, CanonicalMcpServer> = {};
+
+    const mcpServers = raw.mcp_servers as
+      | Record<string, Record<string, unknown>>
+      | undefined;
+    if (
+      typeof mcpServers !== "object" ||
+      mcpServers === null ||
+      Array.isArray(mcpServers)
+    )
+      return {};
+
+    for (const [name, def] of Object.entries(mcpServers)) {
+      const hasUrl = typeof def.url === "string";
+      const isRemote = hasUrl;
+
+      servers[name] = {
+        name,
+        type: isRemote ? "remote" : "local",
+        transport: isRemote ? "http" : undefined,
+        command: def.command as string | undefined,
+        args: def.args as string[] | undefined,
+        url: def.url as string | undefined,
+        env: (def.env as Record<string, string>) || undefined,
+        headers: def.headers as Record<string, string> | undefined,
+        enabled: true,
+      };
+    }
+
+    return servers;
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Read MCP servers from a specific assistant's config file.
  */
@@ -378,6 +442,7 @@ function readAssistantConfig(
 ): Record<string, CanonicalMcpServer> {
   if (platform === "claude-code") return readClaudeConfig(path);
   if (platform === "opencode") return readOpenCodeConfig(path);
+  if (platform === "codex") return readCodexConfig(path);
   return {};
 }
 
@@ -511,6 +576,59 @@ function writeOpenCodeConfig(
   writeFileSync(path, JSON.stringify(existing, null, 2) + "\n");
 }
 
+/**
+ * Write canonical servers to a Codex CLI config.toml file.
+ *
+ * Preserves all non-mcp_servers content in the file.
+ */
+function writeCodexConfig(
+  path: string,
+  servers: Record<string, CanonicalMcpServer>,
+): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Read existing file to preserve non-mcp_servers keys
+  let existing: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    try {
+      existing = TOML.parse(readFileSync(path, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const mcpServers: Record<string, Record<string, unknown>> = {};
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: Record<string, unknown> = {};
+
+    if (server.type === "remote") {
+      if (server.url) entry.url = server.url;
+      if (server.headers) entry.headers = server.headers;
+    } else {
+      if (server.command) entry.command = server.command;
+      if (server.args) entry.args = server.args;
+    }
+
+    if (server.env && Object.keys(server.env).length > 0) {
+      entry.env = server.env;
+    }
+
+    mcpServers[name] = entry;
+  }
+
+  existing.mcp_servers = mcpServers;
+  writeFileSync(
+    path,
+    TOML.stringify(existing as Record<string, unknown>) + "\n",
+  );
+}
+
 /**
  * Write canonical servers to the current assistant's config file.
  */
@@ -521,6 +639,7 @@ function writeAssistantConfig(
 ): void {
   if (platform === "claude-code") writeClaudeConfig(path, servers);
   else if (platform === "opencode") writeOpenCodeConfig(path, servers);
+  else if (platform === "codex") writeCodexConfig(path, servers);
 }
 
 // =============================================================================
@@ -644,7 +763,7 @@ interface McpSource {
  * Gather all MCP config source files for a given scope.
  */
 function gatherSources(scope: McpScope, cwd: string): McpSource[] {
-  const platforms: McpPlatform[] = ["claude-code", "opencode"];
+  const platforms: McpPlatform[] = ["claude-code", "opencode", "codex"];
   const sources: McpSource[] = [];
 
   const aidePath =
@@ -687,6 +806,13 @@ function updateJournalAndResolve(
   const now = new Date().toISOString();
   const activePaths = new Set(sources.map((s) => s.path));
 
+  // Capture servers already in the journal before we process state
+  // transitions. The bootstrap phase should only backfill absence for
+  // these pre-existing servers — not for servers discovered for the
+  // first time in this run — to avoid treating "never existed in
+  // another platform's config" as "intentionally removed".
+  const preExistingServers = new Set(Object.keys(journal.servers));
+
   // Detect state transitions per server per source
   for (const source of sources) {
     const currentNames = new Set(Object.keys(source.servers));
@@ -722,12 +848,14 @@ function updateJournalAndResolve(
     }
   }
 
-  // Bootstrap: for servers found in some sources but absent from others,
-  // record "not present" entries for the missing sources. Without this,
-  // a server deleted from one file before the v2 journal existed would
-  // have no removal event to counterbalance presence in other files.
-  const allServerNames = new Set(Object.keys(journal.servers));
-  for (const serverName of allServerNames) {
+  // Bootstrap: for servers that were already tracked in the journal
+  // before this run, record "not present" entries for sources that
+  // have never been tracked for that server. Without this, a server
+  // deleted from one file before the v2 journal existed would have
+  // no removal event to counterbalance presence in other files.
+  // We only bootstrap pre-existing servers to avoid treating "never
+  // existed in another platform's config" as an intentional removal.
+  for (const serverName of preExistingServers) {
     const sourceMap = journal.servers[serverName];
     for (const source of sources) {
       if (!sourceMap[source.path]) {
@@ -882,13 +1010,7 @@ function syncScope(
       sortedStringify(existingAssistant) !== sortedStringify(assistantServers);
 
     if (assistantChanged) {
-      if (Object.keys(assistantServers).length === 0 && existsSync(p)) {
-        // No servers to write — remove the file rather than leaving
-        // an empty mcpServers block that the assistant still loads.
-        try { unlinkSync(p); } catch { /* ignore */ }
-      } else if (Object.keys(assistantServers).length > 0) {
-        writeAssistantConfig(platform, p, assistantServers);
-      }
+      writeAssistantConfig(platform, p, assistantServers);
       result.modified = true;
     }
   }
@@ -911,7 +1033,7 @@ function syncScope(
  * handles intentional deletions via a journal, and writes the result to
  * both the aide canonical config and the current assistant's config files.
  *
- * @param platform - The current assistant platform ("claude-code" or "opencode")
+ * @param platform - The current assistant platform ("claude-code", "opencode", or "codex")
  * @param cwd - The project working directory
  * @returns Combined sync results for both user and project scopes
  */

package/src/core/types.ts

@@ -111,7 +111,7 @@ export interface Skill {
   path: string;
   triggers: string[];
   description?: string;
-  /** Optional platform restriction. If set, only matched on listed platforms ("opencode", "claude-code"). */
+  /** Optional platform restriction. If set, only matched on listed platforms ("opencode", "claude-code", "codex"). */
   platforms?: string[];
   /** Optional binary requirement. If set, skill is only matched when all listed binaries exist on PATH. */
   requires_binary?: string[];
@@ -156,7 +156,7 @@ export const MAX_PERSISTENCE_ITERATIONS = 20;
  * Identifies which host platform aide is running in.
  * Used for platform-specific behavior like binary discovery or context injection.
  */
-export type AidePlatform = "claude-code" | "opencode" | "unknown";
+export type AidePlatform = "claude-code" | "opencode" | "codex" | "unknown";
 
 /**
  * Options for finding the aide binary.

package/src/hooks/agent-cleanup.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Agent Cleanup Hook (Stop)
+ *
+ * Cleans up agent-specific state when an agent stops.
+ * This prevents stale state from polluting future agents with the same ID.
+ *
+ * Runs after persistence hook to clean up when agent is allowed to stop.
+ */
+
+import { existsSync, appendFileSync } from "fs";
+import { join } from "path";
+import { readStdin } from "../lib/hook-utils.js";
+import { findAideBinary } from "../core/aide-client.js";
+import { cleanupAgent } from "../core/cleanup.js";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "agent-cleanup";
+
+interface HookInput {
+  hook_event_name: string;
+  session_id: string;
+  cwd: string;
+  agent_id?: string;
+  transcript_path?: string;
+  permission_mode?: string;
+}
+
+async function main(): Promise<void> {
+  try {
+    const input = await readStdin();
+    if (!input.trim()) {
+      console.log(JSON.stringify({ continue: true }));
+      return;
+    }
+
+    const data: HookInput = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+    const agentId = data.agent_id || data.session_id;
+
+    // Clean up agent-specific state — delegates to core
+    if (agentId) {
+      const binary = findAideBinary({
+        cwd,
+        pluginRoot:
+          process.env.AIDE_PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT,
+      });
+      if (binary) {
+        const cleared = cleanupAgent(binary, cwd, agentId);
+        if (cleared) {
+          const logDir = join(cwd, ".aide", "_logs");
+          if (existsSync(logDir)) {
+            const logPath = join(logDir, "agent-cleanup.log");
+            const timestamp = new Date().toISOString();
+            appendFileSync(
+              logPath,
+              `${timestamp} Cleaned up state for agent: ${agentId}\n`,
+            );
+          }
+        }
+      }
+    }
+
+    // Always continue - cleanup is best-effort
+    console.log(JSON.stringify({ continue: true }));
+  } catch (error) {
+    debug(SOURCE, `Hook error: ${error}`);
+    console.log(JSON.stringify({ continue: true }));
+  }
+}
+
+process.on("uncaughtException", (err) => {
+  debug(SOURCE, `UNCAUGHT EXCEPTION: ${err}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+process.on("unhandledRejection", (reason) => {
+  debug(SOURCE, `UNHANDLED REJECTION: ${reason}`);
+  try {
+    console.log(JSON.stringify({ continue: true }));
+  } catch {
+    console.log('{"continue":true}');
+  }
+  process.exit(0);
+});
+
+main();