ctx for Codex

The Problem¶

Every Codex session starts from zero. You re-explain your architecture, the AI repeats mistakes it made yesterday, and decisions get rediscovered instead of remembered.

Without ctx:

> "Add the validation middleware we discussed"

I don't have context about previous discussions. Could you describe
what validation middleware you're referring to?

With ctx:

> "Add the validation middleware we discussed"

Yes. From the Jan 15 session. You decided on Zod schemas at the
route level (DECISIONS.md #12), and the pattern is in
CONVENTIONS.md. I'll follow the existing middleware in
src/middleware/auth.ts as a reference.

That's the whole pitch: your AI remembers.

Setup¶

Install the ctx binary first (installation docs), then pick one of the two routes below. Both deliver the same hooks, the same skills, and the same MCP server; they differ only in where the files live.

Route A: The ctx Plugin¶

Register the ctx marketplace and install the plugin:

codex plugin marketplace add ActiveMemory/ctx
codex plugin add ctx@activememory-ctx

Working from a local checkout of the ctx repository? The Makefile wraps both commands (it registers the checkout itself as a local marketplace):

make codex-plugin-install

Then initialize your project:

cd your-project
ctx init

The installed copy lives under $CODEX_HOME/plugins/cache/activememory-ctx/ctx/<version>/ (the version segment is local for a local marketplace). Codex records the enabled state in ~/.codex/config.toml:

[plugins."ctx@activememory-ctx"]
enabled = true

Route B: Project-Local Files¶

From your project root:

ctx setup codex --write && ctx init

ctx setup codex without --write prints the integration overview and what it detected (Codex binary on PATH, plugin installed, plugin enabled) without touching anything.

What Gets Created¶

Re-running --write is safe: existing foreign hook groups in .codex/hooks.json are preserved and only the ctx-managed groups are replaced; an existing [mcp_servers.ctx] table is left alone; a SKILL.md that is not ctx-managed is skipped with a warning instead of overwritten. An unparseable .codex/hooks.json is left untouched (with a warning) while the other steps still run.

[projects."/absolute/path/to/your-project"]
trust_level = "trusted"

Trust the Hooks (Both Routes)¶

Codex refuses to run hooks it has not been told to trust. After either route, start codex in the project, run /hooks, and trust the ctx entries. Until you do, nothing fires and no context is injected.

For a single non-interactive run (CI, smoke tests) you can skip the review with codex exec --dangerously-bypass-hook-trust; the flag applies to that invocation only.

What Happens Automatically¶

Once the hooks are trusted, ctx is wired into Codex's lifecycle. Every hook command starts with cd "$(git rev-parse --show-toplevel)" && because Codex runs hooks with the session cwd and ctx reads $PWD/.context/; the anchor makes a subdirectory cwd harmless.

PermissionRequest, PreCompact, PostCompact, SubagentStart, SubagentStop, and Stop are not wired: no ctx behavior maps onto them today.

What Is Different from Claude Code¶

• The context packet arrives at SessionStart rather than on the first tool call. Codex ignores plain text on PreToolUse, and SessionStart output becomes developer context directly.
• The planning matcher is update_plan (Claude Code: EnterPlanMode), and file edits arrive as apply_patch.
• Codex caps SessionEnd hooks at 3 seconds. The journal import is incremental (one stat per already-imported session), so it normally finishes well inside that; if it does not, Codex reports a hook failure and the next check-journal nudge or the next session end picks up where it left off.

Skills¶

The plugin and the project-local route both ship the ctx skills as Codex skills. Invoke them with a $ prefix:

The Codex skill set is generated from the Claude Code skills (hack/sync-codex-skills.sh strips the Claude-only allowed-tools: frontmatter). Four skills are Claude Code-only and are not shipped: ctx-permission-sanitize (audits .claude/settings.local.json), ctx-plan-import (reads ~/.claude/plans/), ctx-dream (headless claude -p cron), and ctx-skill-create (authors Claude Code skills). Skill bodies that mention /ctx-remember and friends refer to the same skill under its $ctx-remember name.

MCP Tools¶

Both routes register the ctx MCP server (ctx mcp serve): the plugin through its bundled .mcp.json, the project-local route through [mcp_servers.ctx] in .codex/config.toml. The server exposes these tools to the agent:

You don't invoke these yourself. The agent uses them as needed.

Session History¶

Codex writes a rollout transcript per session under $CODEX_HOME/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl (default ~/.codex/sessions). ctx journal import discovers them, matches them to the current project by the session's working directory, and imports them with the tool id codex:

ctx journal import --all              # Codex sessions land alongside Claude Code ones
ctx journal source --tool codex       # list only Codex sessions

Developer-injected items (<environment_context>, <user_instructions>, skill and permission preambles) are filtered out; a rollout with no real user message is skipped. The SessionEnd hook runs the same import on the way out of every session.

Steering Files¶

Codex is not a steering sync target. It receives inclusion: always steering files inside the SessionStart context packet and can fetch auto/manual files on demand through the ctx_steering_get MCP tool. With tool: codex in .ctxrc, ctx steering sync prints an info line and exits 0 instead of writing anything. See How Claude Code and Codex Consume Steering.

Already on Claude Code?¶

Codex ships a /import command that copies Claude Code hooks, skills, and MCP servers into Codex. It works for ctx too, but prefer ctx setup codex --write or the plugin: the Codex manifest anchors commands to the git root instead of ${CLAUDE_PROJECT_DIR}, moves the context packet to SessionStart, uses Codex's update_plan and apply_patch matchers, and sets the 3-second SessionEnd timeout. An imported Claude manifest carries none of that.

Known Limitations¶

• Hooks load only in trusted projects. Project-local files are ignored until the directory is trusted (see above). The plugin route does not have this constraint.
• SessionEnd is capped at 3 seconds by Codex. The import is incremental, so a timeout only delays the import to the next sweep.
• No Windows commandWindows override is shipped, matching the Claude Code manifest; hooks require a POSIX shell with git on PATH.
• Codex memories are not bridged. ~/.codex/memories/ is generated, opaque state with no documented file contract, so ctx leaves it alone (unlike the Claude Code MEMORY.md bridge).
• No status line. Codex has no statusline hook.

Refreshing the Integration¶

• Plugin route: Codex caches plugins by version. After bumping VERSION (make sync-version updates internal/assets/codex/.codex-plugin/plugin.json and .agents/plugins/marketplace.json together), re-run codex plugin add ctx@activememory-ctx and start a new session.
• Project-local route: re-run ctx setup codex --write. Stale ctx-managed hook groups and skills are refreshed in place; your own hook groups and config.toml content are preserved.
• Skills drift check: make check-codex-skills fails when internal/assets/codex/skills/ is out of sync with the Claude Code skills; make sync-codex-skills regenerates it.

Troubleshooting¶

Verify It Works¶

Start a new Codex session in the project and ask:

Do you remember?

The AI should cite specific context: current tasks, recent decisions, or previous session topics. If it says "I don't have memory" or "Let me check," something went wrong; confirm the hooks are trusted and .context/ has files in it.

What's Next¶

• Your First Session: step-by-step walkthrough from ctx init to verified recall.
• Common Workflows: day-to-day commands for tracking context, checking health, and browsing history.
• Context Files: what lives in .context/ and how each file is used.
• AI Tools: the hook manifest, the event table, and the drift checks that keep this page honest.