Codex CLI
Install context-mode on Codex CLI through its plugin marketplace — add the marketplace, enable two feature flags, and optionally copy the routing file.
Codex CLI integrates context-mode through six JSON hooks. Each event dispatches
through context-mode hook codex <event>, with the event token lowercased (e.g.
context-mode hook codex pretooluse). Together these hooks route data-heavy
tool output into the sandbox and keep the bulk of raw payload bytes out of your
window — the model writes a program that processes the data and prints only the
answer.
PreToolUsePostToolUseSessionStartPreCompactUserPromptSubmitStop
PreToolUse enforces deny routing on every build. Newer builds add command
rewrites and context injection, detected at runtime via codex --version:
| codex-cli build | PreToolUse behavior |
|---|---|
| 0.141.0 or newer | Deny routing plus command rewrites (updatedInput) and context injection (additionalContext) |
| Older builds | Deny routing only — rewrites degrade to a deny, so routing still works, it just blocks instead of rewriting |
Prerequisites: Node.js 22.5 or newer (or Bun) and Codex CLI installed. The
plugin marketplace command installs the server and hooks. Copying the optional
AGENTS.md routing file (and the manual fallback for builds without
plugin_hooks) uses the global npm package, so install it with
npm install -g context-mode if you take either of those paths. Codex also
needs node visible on its PATH.
Install
Add the marketplace
Register the context-mode plugin marketplace inside Codex CLI, then install the
plugin from Codex's plugin UI. The plugin manifest provides the MCP server
(.codex-plugin/mcp.json), bundled hooks (.codex-plugin/hooks.json), and
skills.
codex plugin marketplace add mksglu/context-modeEnable the feature flags
context-mode reads a single flag — [features].hooks — to know that hooks are
active. The bundled-plugin hook path additionally needs Codex's own
plugin_hooks gate, so the marketplace install above wants both flags. In the
Codex config, set both under a [features] section:
[features]
plugin_hooks = true
hooks = trueplugin_hooks is a Codex-side gate for the bundled-plugin hook path only — it
is not something context-mode itself reads. If you wire hooks manually (the
standalone fallback below), you only need [features].hooks = true; leave
plugin_hooks out.
The hooks file then lives under your Codex home directory.
Restart Codex
Restart so the feature flags take effect and the hooks register.
Standalone install (Codex builds without plugin_hooks)
If your Codex build does not expose plugin_hooks, register context-mode
manually instead of through the marketplace. The doctor accepts this path as a
valid install.
Install the global package, then add the MCP server and [features].hooks to
~/.codex/config.toml:
npm install -g context-mode[features]
hooks = true
[mcp_servers.context-mode]
command = "context-mode"Then create $CODEX_HOME/hooks.json (or ~/.codex/hooks.json when CODEX_HOME
is unset) wiring all six events. The bundled template at
configs/codex/hooks.json is the source of truth — copy it directly:
CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/hooks.json" "${CODEX_HOME:-$HOME/.codex}/hooks.json"Each event dispatches context-mode hook codex <event> for pretooluse,
posttooluse, sessionstart, precompact, userpromptsubmit, and stop.
Copy the routing instructions (recommended)
Codex PreToolUse is deny-only and cannot rewrite tool input, so a routing
instructions file materially improves how reliably the model routes data-heavy
work into the sandbox. Copy the bundled AGENTS.md into your project (or your
Codex home directory for all projects). If both exist, Codex merges them.
CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ./AGENTS.md
# or, globally:
cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.codex/AGENTS.mdVerify
Confirm the install with the doctor. It checks that the codex binary is on
your PATH, that [features].hooks is true, the MCP registration (the
marketplace plugin or a standalone [mcp_servers.context-mode] block both
pass), and that each hook event is configured.
context-mode doctorYou can run the same check inside the chat with ctx doctor. A clean run means
context-mode is ready to route your next data-heavy command.
The doctor also surfaces several Codex-specific signals worth knowing about:
| Signal | What it means |
|---|---|
| Deprecation warning | You still use [features].codex_hooks instead of [features].hooks. |
| "Codex plugin root" mismatch | The configured root and the runtime root from codex plugin list disagree. |
| "Standalone MCP duplicate" | Both the plugin and a standalone [mcp_servers.context-mode] block are registered. |
| Per-event duplicate-hook warning | More than one context-mode entry is wired for the same event, which doubles hook work and bloats the logs. |
For most of these, context-mode upgrade is the one-command fix — it repairs
the config and collapses duplicates while leaving unrelated hooks alone.
Once the server is reachable, context-mode exposes its MCP tool surface to Codex:
- Sandbox tools:
ctx_execute,ctx_execute_file,ctx_batch_execute,ctx_fetch_and_index,ctx_search,ctx_index - Meta tools:
ctx_stats,ctx_doctor,ctx_upgrade,ctx_purge,ctx_insight
Caveats
Codex capabilities are gated on the Codex build, detected at runtime via
codex --version. Deny routing works on every build; rewrite, injection, and
snapshot capabilities depend on the version.
| Capability | Availability |
|---|---|
PreToolUse deny routing | Every build — can block a dangerous or data-heavy call. |
Tool-input rewrite (updatedInput) | codex-cli 0.141.0 or newer. On older builds the response fails closed, so a redirect becomes a deny. |
PreToolUse context injection (additionalContext) | codex-cli 0.141.0 or newer. On older builds the response fails closed, so a redirect becomes a deny. |
Output modification (updatedMCPToolOutput) | Never supported — output-side context is injected in PostToolUse instead. |
PreCompact snapshots | Present in Codex CLI 0.130.0. Builds that do not emit the event create no pre-compaction snapshots. |
PostToolUse does not fire for a failing tool call (an upstream Codex
limitation), so a command that errors out is not captured on the output side.
When a build does not emit PreCompact, no pre-compaction snapshot is created
— SessionStart restores the snapshot afterward.
If Codex cannot write to the default storage directory, set CONTEXT_MODE_DIR
to a writable absolute path in the environment that launches Codex so the
knowledge base and session data land somewhere Codex can write.
CONTEXT_MODE_DIR="$HOME/.codex-context-mode" codexVerify your savings
Confirm context-mode is actually saving you tokens, not just installed.
- In a Codex session, type
ctx statsto see tokens saved, the savings ratio, and a per-tool breakdown for the session. This also proves the MCP server is reachable. - Run
context-mode doctor(orctx doctorin chat) to confirm:- the
codexbinary is onPATH [features].hooksistrue- the MCP server is registered
- every hook event is wired
- the
- If the doctor flags a deprecated flag, a plugin-root mismatch, a
standalone-MCP duplicate, or duplicate hook entries, run
context-mode upgradeto auto-repair. - To check hook routing, confirm Codex lists and trusts the context-mode plugin hooks, then run a command that matches the routing rules.