@jmylchreest/aide-plugin 0.0.56 → 0.0.58

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,
@@ -17,19 +18,84 @@
 import {
   existsSync,
   readFileSync,
+  readdirSync,
   writeFileSync,
   mkdirSync,
   statSync,
 } 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.
+ *
+ * Scans plugin cache and marketplace directories for plugin.json files
+ * and returns the set of MCP server names they define. These servers
+ * must not be synced from assistant configs — doing so would override
+ * the plugin's own definition and bypass CLAUDE_PLUGIN_ROOT.
+ */
+function getPluginManagedServers(): Set<string> {
+  const names = new Set<string>();
+  const pluginsDir = join(homedir(), ".claude", "plugins");
+
+  // Scan both cache (installed plugins) and marketplaces (git-cloned plugins)
+  const searchDirs = [
+    join(pluginsDir, "cache"),
+    join(pluginsDir, "marketplaces"),
+  ];
+
+  for (const baseDir of searchDirs) {
+    if (!existsSync(baseDir)) continue;
+
+    try {
+      // Walk up to 3 levels deep to find .claude-plugin/plugin.json
+      // cache: <marketplace>/<plugin>/<version>/.claude-plugin/plugin.json
+      // marketplaces: <name>/.claude-plugin/plugin.json
+      const findPluginJsons = (dir: string, depth: number): string[] => {
+        if (depth > 3) return [];
+        const results: string[] = [];
+        const pluginJson = join(dir, ".claude-plugin", "plugin.json");
+        if (existsSync(pluginJson)) results.push(pluginJson);
+
+        try {
+          for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory() && !entry.name.startsWith(".")) {
+              results.push(...findPluginJsons(join(dir, entry.name), depth + 1));
+            }
+          }
+        } catch {
+          // Permission or read error — skip
+        }
+        return results;
+      };
+
+      for (const pluginJsonPath of findPluginJsons(baseDir, 0)) {
+        try {
+          const content = JSON.parse(readFileSync(pluginJsonPath, "utf-8"));
+          if (content.mcpServers && typeof content.mcpServers === "object") {
+            for (const serverName of Object.keys(content.mcpServers)) {
+              names.add(serverName);
+            }
+          }
+        } catch {
+          // Skip unparseable plugin.json files
+        }
+      }
+    } catch {
+      // Directory read error — skip
+    }
+  }
+
+  return names;
+}
 
 /** Scope level for config files. */
 export type McpScope = "user" | "project";
@@ -139,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 [];
 }
 
@@ -157,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 [];
 }
 
@@ -304,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.
  */
@@ -313,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 {};
 }
 
@@ -446,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.
  */
@@ -456,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);
 }
 
 // =============================================================================
@@ -579,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 =
@@ -782,7 +966,7 @@ function syncScope(
     if (!bestPresent) result.skipped++;
   }
 
-  // Write to aide canonical config (if changed)
+  // Write to aide canonical config (if changed) — includes ALL servers
   const sortedStringify = (obj: object) =>
     JSON.stringify(obj, Object.keys(obj).sort());
   const aideChanged =
@@ -793,21 +977,37 @@ function syncScope(
     result.modified = true;
   }
 
+  // For Claude Code, exclude servers managed by plugins — these are
+  // defined in plugin.json and must not be written to assistant configs
+  // (doing so overrides the plugin's definition and bypasses
+  // CLAUDE_PLUGIN_ROOT). The aide canonical config keeps them so they
+  // can still sync to non-plugin assistants like OpenCode.
+  let assistantServers = finalServers;
+  if (platform === "claude-code") {
+    const pluginManaged = getPluginManagedServers();
+    if (pluginManaged.size > 0) {
+      assistantServers = { ...finalServers };
+      for (const name of pluginManaged) {
+        delete assistantServers[name];
+      }
+    }
+  }
+
   // Write to current assistant's config
   const assistantPaths = getAssistantWritePaths(platform, scope, cwd);
   for (const p of assistantPaths) {
     const existingAssistant = readAssistantConfig(platform, p);
     const assistantChanged =
-      sortedStringify(existingAssistant) !== sortedStringify(finalServers);
+      sortedStringify(existingAssistant) !== sortedStringify(assistantServers);
 
     if (assistantChanged) {
-      writeAssistantConfig(platform, p, finalServers);
+      writeAssistantConfig(platform, p, assistantServers);
       result.modified = true;
     }
   }
 
-  result.serversWritten = Object.keys(finalServers).length;
-  result.serverNames = Object.keys(finalServers);
+  result.serversWritten = Object.keys(assistantServers).length;
+  result.serverNames = Object.keys(assistantServers);
 
   return result;
 }
@@ -824,7 +1024,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.