> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> TOML MCP wiring, the Codex plugin, and the Desktop hooks workaround

## Setup

<Steps>
  <Step title="Start agentmemory">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory
    ```
  </Step>

  <Step title="Wire MCP">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory connect codex
    ```

    The adapter detects `~/.codex/`, backs up `config.toml`, and appends the server block. On Codex Desktop, add `--with-hooks` (see below).
  </Step>

  <Step title="Install the Codex plugin (recommended)">
    ```bash theme={"dark"}
    codex plugin marketplace add rohitg00/agentmemory
    codex plugin add agentmemory@agentmemory
    ```

    The plugin ships from the same `plugin/` directory as the Claude Code plugin and registers the MCP server, 6 lifecycle hooks, and 17 skills.
  </Step>

  <Step title="Restart Codex">
    Codex picks up MCP servers on next launch.
  </Step>

  <Step title="Verify">
    ```bash theme={"dark"}
    codex mcp list
    curl http://localhost:3111/agentmemory/health
    ```

    `codex mcp list` should show `agentmemory` as enabled. Run one prompt, then check the Sessions tab at `http://localhost:3113` for hook-captured observations — and if none appear, see the hook trust approval below.
  </Step>
</Steps>

## What connect writes

```toml ~/.codex/config.toml theme={"dark"}
[mcp_servers.agentmemory]
command = "npx"
args = ["-y", "@agentmemory/mcp"]

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "http://localhost:3111"
```

Re-running with `--force` strips the existing `[mcp_servers.agentmemory]` block first and appends a fresh one, so the file never accumulates duplicates. The write is verified by re-reading the file.

## Capture model

The plugin registers 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`. Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses, so the same hook scripts run unmodified across Claude Code and Codex. Subagent, SessionEnd, Notification, TaskCompleted, and PostToolUseFailure events are Claude Code only and are not registered for Codex.

The plugin also registers 9 invocable skills (`/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`) plus 8 reference skills the agent loads on demand.

## Codex Desktop: `--with-hooks` workaround

<Warning>
  Codex Desktop builds currently do not dispatch plugin-local `hooks.json` even though the `CodexHooks` and `PluginHooks` feature flags are stable and default-enabled (openai/codex#16430). MCP tools still work; only the lifecycle observations go missing.
</Warning>

Until upstream fixes plugin-scope dispatch, mirror the same hook commands into the global hooks file:

```bash theme={"dark"}
npx @agentmemory/agentmemory connect codex --with-hooks
```

This merges the bundled `hooks.codex.json` manifest into `~/.codex/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` resolved to the absolute bundled `plugin/` path. The merge is idempotent: re-installs strip only entries whose command points under the bundled `scripts/` directory, and your own hook entries survive. It runs even when MCP is already wired.

<Warning>
  **Codex requires a one-time interactive trust approval before any new hook runs.** Launch `codex` (the TUI) once after `--with-hooks`; it shows "Hooks need review — N hooks are new or changed" — choose **Trust all and continue**. Codex records a per-hook `trusted_hash` in `config.toml`, and only trusted hooks execute. `codex exec` never shows this prompt, so hooks stay silently inert on exec-only usage until the TUI approval happens. The approval also re-triggers whenever a hook command changes (including the path refresh after upgrading agentmemory).
</Warning>

<Note>
  The merged entries reference absolute, version-embedding paths. Re-run `agentmemory connect codex --with-hooks` after upgrading agentmemory to refresh them, then re-approve in the TUI.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP tools work but no observations are captured">
    Two causes, in order of likelihood. First: the hooks were never trusted — codex runs only hooks with a recorded `trusted_hash`, and the "Hooks need review" prompt appears only in the interactive TUI, so launch `codex` once and choose Trust all (a `codex exec`-only workflow never sees the prompt and the hooks stay inert, while codex still prints `hook: ... Completed` for other tools' trusted hooks, which is easy to misread). Second: you are on Codex Desktop relying on plugin-local hooks, which are currently silent there (openai/codex#16430) — run `connect codex --with-hooks` to mirror the hooks into `~/.codex/hooks.json`, then trust them in the TUI.
  </Accordion>

  <Accordion title="Hooks fallback skipped: could not locate bundled plugin/ directory">
    The installer resolves the bundled `plugin/` directory of the installed `@agentmemory/agentmemory` package. Reinstall the package (`npm install -g @agentmemory/agentmemory`) and re-run. The MCP wiring is applied regardless of this skip.
  </Accordion>
</AccordionGroup>

Adapter source: `src/cli/connect/codex.ts` and `src/cli/connect/codex-hooks.ts`. Hook manifest: `plugin/hooks/hooks.codex.json`.