Hydrate for Codex — install in five minutes

After this page: Codex CLI and the Codex macOS App both inject memory from your local Hydrate store on every prompt. A fact you pinned in a Claude Code session will appear in Codex without you doing anything extra.

Prerequisites

• Hydrate installed (hydrate doctor all-green). See Free install.
• Codex CLI (codex --version returns codex-cli 0.130.0 or later), or the Codex macOS App installed.

Install

hydrate install-hooks

install-hooks automatically detects ~/.codex/ and wires Hydrate's hooks alongside the Claude Code hooks in a single run. Use --codex-only to skip the Claude Code side:

hydrate install-hooks --codex-only

What gets written:

~/.codex/hooks.json — three hook entries:

{
  "hooks": {
    "UserPromptSubmit": [{ "type": "command", "command": "~/.local/bin/codex-context",       "timeout": 3 }],
    "Stop":             [{ "type": "command", "command": "~/.local/bin/codex-capture",        "timeout": 15 }],
    "SessionStart":     [{ "type": "command", "command": "~/.local/bin/codex-session-start",  "timeout": 3 }]
  }
}

~/.codex/config.toml — one line added or enabled:

[features]
hooks = true

Codex silently ignores hooks.json unless [features] hooks = true is set. If your config already has hooks = false, the installer upgrades it to true and prints a warning.

Verify

hydrate doctor --advanced

Look for three green lines:

✓ Codex CLI                   codex-cli 0.130.0 — /opt/homebrew/bin/codex
✓ Codex hooks armed           active: ~/.codex/hooks.json; [features] hooks = true
✓ Project-ID sentinel         0 facts with empty/NULL project_id

If Codex is not installed, those checks show "codex not installed" and soft-skip — that is expected.

Then open Codex in any project and submit a prompt. After the session ends, check the local DB:

sqlite3 ~/.hydrate/data.db \
  "SELECT datetime(ended_at), project, source FROM sessions ORDER BY ended_at DESC LIMIT 5"

You should see rows with source = 'codex-cli' or source = 'codex-app'.

What each shim does

codex-context (UserPromptSubmit)

Same role as claude-context on Claude Code: queries the local Hydrate store for facts relevant to the current prompt and injects them as additional context before the prompt reaches the model. 3 s timeout; fail-open.

codex-capture (Stop)

Same role as claude-capture: imports the session transcript into ~/.hydrate/data.db and runs a micro-consolidation. Detects whether the input is a Codex JSONL (rollout format with payload.content[].text) and translates it into Hydrate's internal format before saving.

codex-session-start (SessionStart)

Re-injects the recovery snapshot from the previous session, same as claude-session-start on Claude Code.

Cross-runtime memory demo

After a few sessions in both Claude Code and Codex, you can verify the shared memory:

Step 1 — Pin a fact in a Claude Code session:

hydrate canon add --project=my-project "prefer explicit error returns over panic in Go"

Step 2 — Open a fresh Codex session in the same project directory. Submit a prompt that relates to error handling.

Step 3 — Check what was injected:

sqlite3 ~/.hydrate/data.db <<'SQL'
  SELECT datetime(retrieved_at), endpoint, project_id
  FROM hydrate_retrievals
  WHERE project_id = 'my-project'
  ORDER BY id DESC
  LIMIT 5;
SQL

You should see a recent row for the Codex session's UserPromptSubmit retrieval. The fact from step 1 is now reaching the model in Codex without re-entering it.

The reverse also works: pin a fact in Codex, it appears in your next Claude Code session.

Codex macOS App

The macOS App reads the same ~/.codex/ directory as the CLI. After hydrate install-hooks, open or restart the App — no separate install step. The App fires the same UserPromptSubmit, Stop, and SessionStart events.

The only difference: the App's session transcripts use source = 'codex-app' in the sessions table (not codex-cli), so they are distinguishable in the dashboard.

What changed on your machine

Opt out

To disable Hydrate's Codex integration without affecting Claude Code:

1. Edit ~/.codex/config.toml: set hooks = false under [features].
2. Confirm: hydrate doctor --advanced should show the Codex hooks as disabled.

To re-enable: set hooks = true and restart the CLI or App.

Troubleshooting

Next steps

• Claude Code integration — hook details for the Claude side
• Vibe integration — add Mistral Vibe to the same memory substrate
• Pro install — unlock Hydration Packs for portable cross-runtime bundles