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 JSON hooks: a deny-only PreToolUse, plus PostToolUse, SessionStart, PreCompact, UserPromptSubmit, and Stop. Those 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.

The plugin marketplace command installs the server and hooks. Copying the optional AGENTS.md routing file (and the manual fallback for older Codex builds) 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-mode

Enable the feature flags

Codex CLI gates plugin hooks behind feature flags. In the Codex config, set both plugin_hooks and hooks to true under a [features] section.

[features]
plugin_hooks = true
hooks = true

The hooks file then lives under your Codex home directory.

Restart Codex

Restart so the feature flags take effect and the hooks register.

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.md

Verify

Confirm the install with the doctor. It checks language runtimes, the FTS5 knowledge base, and hook registration, then reports anything that needs attention.

context-mode doctor

A clean run means context-mode is ready to route your next data-heavy command.

Caveats

Codex CLI has three integration limits. PreToolUse blocking is deny-only — it can refuse a call but not transform it. Modified tool input is dropped silently. And additionalContext is not supported, so context is injected in PostToolUse instead of before the tool runs.

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" codex

Configuration

Environment variables, storage, and permission rules.

Configuration

On this page