Codex hooks fallback skipped: ${hookResult.reason}. MCP wiri

Error message

Codex hooks fallback skipped: ${hookResult.reason}. MCP wiring still applied.

What it means

`agentmemory connect codex --with-hooks` wires the Codex MCP server and optionally installs hooks via installCodexHooks(). If that installer returns { kind: "skipped", reason }, the CLI logs this warning rather than failing, since MCP wiring already succeeded. Only the optional hooks fallback was not applied.

Source

Thrown at src/cli/connect/codex.ts:122

    writeFileSync(CODEX_TOML, next, "utf-8");

    const verify = readFileSync(CODEX_TOML, "utf-8");
    if (!isWiredText(verify)) {
      p.log.error(
        `Verification failed: ${CODEX_TOML} did not contain ${SECTION_HEADER} after write.`,
      );
      return { kind: "skipped", reason: "verification-failed" };
    }

    logInstalled("Codex CLI", CODEX_TOML);
    p.log.info(
      "Codex picks up MCP servers on next launch. For the deeper plugin install, run: codex plugin marketplace add rohitg00/agentmemory && codex plugin add agentmemory@agentmemory",
    );

    if (opts.withHooks) {
      const hookResult = installCodexHooks(opts);
      if (hookResult.kind === "skipped") {
        p.log.warn(
          `Codex hooks fallback skipped: ${hookResult.reason}. MCP wiring still applied.`,
        );
      }
    }

    return {
      kind: "installed",
      mutatedPath: CODEX_TOML,
      ...(backupPath !== undefined && { backupPath }),
    };
  },
};

/**
 * Install the global `~/.codex/hooks.json` fallback. See
 * `codex-hooks.ts` for context (openai/codex#16430). Returns a result
 * describing the side effect for the caller's summary; failures here do
 * not roll back the MCP wiring.

View on GitHub (pinned to e04ba88819)

Solutions

Read hookResult.reason in the warning — it names the exact blocking condition.
Launch `codex` once so its config/hooks files are created, then re-run `agentmemory connect codex --with-hooks`.
Verify CODEX_HOME (if customized) points to the directory agentmemory expects and is writable.
If you only need MCP wiring, ignore the warning and confirm the server with `codex mcp list` / next launch.
Optionally use the deeper plugin install: `codex plugin marketplace add rohitg00/agentmemory && codex plugin add agentmemory@agentmemory`.

Example fix

// before
agentmemory connect codex --with-hooks
// -> warning: Codex hooks fallback skipped: config file not found ...

// after
codex --version          # run once to create config files
agentmemory connect codex --with-hooks   # re-run; hooks installed

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import { join } from "node:path";
const codexHome = process.env.CODEX_HOME ?? join(process.env.HOME ?? "", ".codex");
if (!existsSync(codexHome)) {
  console.error("Codex config dir missing — launch `codex` once before `connect codex --with-hooks`.");
  process.exit(1);
}

Type guard

type HookInstallResult = { kind: "installed" } | { kind: "skipped"; reason: string };
function hookSkipped(r: unknown): r is { kind: "skipped"; reason: string } {
  return typeof r === "object" && r !== null && "kind" in r && (r as any).kind === "skipped";
}

Try / catch

try {
  const hookResult = installCodexHooks(opts);
  if (hookResult.kind === "skipped") {
    console.warn(`Codex hooks skipped (${hookResult.reason}); MCP wiring still applied.`);
  }
} catch (err) {
  console.warn("Codex hook install threw; MCP wiring remains applied:", err);
}

Prevention

Run `codex` once to create its config/hooks files before connecting with --with-hooks.
Verify CODEX_HOME / ~/.codex exists and is writable.
Remember MCP wiring and hooks are independent — a hooks skip does not affect the MCP server entry.
Re-run the connect command after fixing the environment.

When it happens

Trigger: Running `agentmemory connect codex --with-hooks` when installCodexHooks() returns a 'skipped' result — typically because the Codex config/hooks file cannot be located, the config directory does not exist, or a precondition of the hook installer fails.

Common situations: Codex installed but never launched (no config dir), a non-default CODEX_HOME, read-only or permission-restricted config paths, or stale Codex versions with different config layouts. Developers then see MCP working but no hook-based context recall in Codex sessions.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/0ea6454e5cd2496f. Report an issue: GitHub.