Set up Agent Monitor for Codex

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

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 — 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. Non-managed hooks are inert until reviewed — Codex silently skips untrusted hooks, so this step is required before any activity appears.

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, and the requirements file overrides each user's config.toml and CLI flags — 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 — disabling 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