Skip to main content

Set up Agent Monitor for Codex

Install hook scripts to send OpenAI Codex agent activity to MintMCP for monitoring and rule enforcement.

MintMCP registers the same three hook events for Codex as for Claude Code: UserPromptSubmit for prompts, plus PreToolUse and PostToolUse for tool calls, covering supported shell commands, apply_patch file edits, and MCP tool calls. Web search and some shell calls sit outside Codex hook coverage today. Rule actions also enforce differently in some phases, so check the support matrix when writing mask rules.

Prerequisites​

  • Agent Monitor Setup access with admin permissions
  • Codex CLI 0.141 or later (hooks require 0.141+)

Generate an organization key​

  1. Go to Agent Monitor Setup
  2. Select the Codex tab
  3. Click Generate Organization Key if needed

Install hook files​

Local installation​

For a single user on their own machine. Create the Codex configuration directory:

mkdir -p ~/.codex

Step 1. Add the hook configuration​

Codex reads hooks from either ~/.codex/config.toml or a standalone ~/.codex/hooks.json. Choose one.

config.toml registers the relay and enables hooks in your existing config:

[features]
hooks = true

[[hooks.PreToolUse]]
matcher = "*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "sh ~/.codex/mint.sh"
timeout = 600

[[hooks.PostToolUse]]
matcher = "*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "sh ~/.codex/mint.sh"
timeout = 600

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "sh ~/.codex/mint.sh"
timeout = 600

hooks.json is a standalone file with no config.toml edit. Hooks are enabled by default on Codex 0.141:

{
  "hooks": {
    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "sh ~/.codex/mint.sh" }] }],
    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "sh ~/.codex/mint.sh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "sh ~/.codex/mint.sh" }] }]
  }
}

Step 2. Create the relay script​

Save ~/.codex/mint.sh with the script from the MintMCP UI. It relays Codex activity to MintMCP for logging and rule evaluation. The script fails open if MintMCP is unreachable, so it never blocks your local agent.

Optional: set MINTMCP_USER in the script to customize the display name in logs (defaults to $USER). You can also set this from the Display name for logs field in the UI before copying.

Step 3. Trust the hooks​

Run codex, then /hooks, and approve the MintMCP hooks. Codex silently skips untrusted hooks, so no activity appears until you complete this step.

Managed deployment (MDM)​

Deploy hooks organization-wide through Codex's requirements layer. Hooks delivered this way are admin-enforced and trusted automatically, so users skip the /hooks approval step. The requirements file overrides each user's config.toml and CLI flags, which means local config can't undo it. The relay is a POSIX sh script, so this path targets macOS and Linux.

Step 1. Deploy the requirements file​

Push this to /etc/codex/requirements.toml, or to the macOS MDM preference key com.openai.codex:requirements_toml_base64:

[features]
hooks = true

[hooks]
managed_dir = "/etc/codex/hooks"

[[hooks.PreToolUse]]
matcher = "*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "sh /etc/codex/hooks/mint.sh"
timeout = 600

[[hooks.PostToolUse]]
matcher = "*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "sh /etc/codex/hooks/mint.sh"
timeout = 600

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "sh /etc/codex/hooks/mint.sh"
timeout = 600

By default MintMCP monitoring layers on top of any hooks users already run. To enforce only managed hooks, which disables each user's own user, project, session, and plugin hooks, add allow_managed_hooks_only = true above the [features] block.

Step 2. Deliver the relay script​

Codex has no HTTP hook, so the relay still runs as a local script. Ship the mint.sh from the MintMCP UI to /etc/codex/hooks/mint.sh on each machine with your file-delivery tool (such as Jamf, Intune, or Salt). Both files must reach the machine: the requirements.toml and the mint.sh it points at. MINTMCP_USER defaults to $USER, so each machine reports its own user.

See Codex's hooks documentation for more on managed-hook delivery.

Verify​

  1. For local installs, confirm the hooks are trusted by running /hooks in Codex (managed hooks are trusted automatically)
  2. Run an agent action (submit a prompt, execute a command)
  3. Check Live Activity for the logged action

Troubleshooting​

If activity doesn't appear:

  • Confirm mint.sh and your hook config reached the machine (~/.codex for local, /etc/codex for managed)
  • For local installs, run /hooks in Codex to confirm the MintMCP hooks are trusted and enabled
  • Confirm hooks are enabled ([features] hooks = true, on by default)
  • Verify your organization key is valid and hasn't been regenerated

Other clients​