@pmatrix/codex-monitor

Runtime safety governance for OpenAI Codex CLI — active intervention, not just logging.

Blocks dangerous tool calls before execution, detects credential leaks in user prompts, and continuously measures agent risk with live Trust Grade (A–E).

Requires a P-MATRIX account, API key, and Codex CLI v0.124.0+ (hooks GA, 2026-04-23).

What it does

Core Protection

• Safety Gate — Intercepts high-risk tool calls (Bash, apply_patch, mcp__*) before execution. Blocks based on current risk level R(t).
• Credential Protection — Detects and blocks 16 types of API keys and secrets in user prompts before they reach the agent.
• Kill Switch — Automatically halts the agent when R(t) ≥ 0.75. Manually via ~/.pmatrix/HALT (shared across 5 P-MATRIX SDKs — Claude Code / Cursor / Gemini / OpenClaw / Codex).

Codex-specific Features

• apply_patch AP-2 — Direct observation of file edits via apply_patch (or Edit/Write matchers). Path extraction + scope tagging.
• tool_name identification — Bash (shell), apply_patch (file edit), mcp__<server>__<tool> (MCP tools).
• requirements.toml support (v0.2+) — Codex CLI's enterprise hook system for organization-wide governance enforcement.

Behavioral Intelligence

• Tool Failure Tracking — Records each tool failure and applies a stability nudge.
• Live Grade — Streams 4-axis safety signals and displays Trust Grade (A–E) in real time.

Hooks (6)

| Hook | Role | Block? | |:---|:---|:---| | SessionStart | Session bootstrap | — | | UserPromptSubmit | Credential scan (16 patterns) | exit 2 | | PreToolUse | Safety Gate core | JSON deny | | PermissionRequest | Approval workflow | JSON deny | | PostToolUse | R(t) update + apply_patch AP-2 | — | | Stop | session_report + breach flush | — |

Requirements

| Requirement | Version | |:---|:---| | Node.js | >= 18 | | Codex CLI | v0.124.0+ (hooks GA) | | P-MATRIX server | v1.0.0+ | | Platform | macOS / Linux / Windows |

Install

npm install -g @pmatrix/codex-monitor
pmatrix-codex setup --agent-id <YOUR_AGENT_ID>
export PMATRIX_API_KEY=<YOUR_API_KEY>

setup writes hook configuration to ~/.codex/hooks.json. Use --repo flag to write to <cwd>/.codex/hooks.json instead (per-repository setup).

Restart Codex CLI to activate monitoring.

Configuration

| Env var | Default | Description | |:---|:---|:---| | PMATRIX_API_KEY | (required) | Your P-MATRIX API key | | PMATRIX_AGENT_ID | (required) | Your agent identifier | | PMATRIX_SERVER_URL | https://api.pmatrix.io | Server URL | | PMATRIX_LOCAL_URL | (optional) | Local sidecar URL — try sidecar first, fall back to server | | PMATRIX_DEBUG | 0 | Set to 1 to log debug info to stderr | | PMATRIX_DEBUG_TRACE | 0 | Set to 1 to log X-Request-ID echo to stderr |

P-MATRIX 5 SDK Family

| SDK | Hook count | Distinguishing feature | |:---|:---:|:---| | @pmatrix/openclaw-monitor | 28+ events | In-process plugin, richest hook surface | | @pmatrix/claude-code-monitor | 19 hooks | Command Hook + MCP, file-persisted state | | @pmatrix/cursor-monitor | 14 hooks | Shell command direct analysis + AP-2 bidirectional | | @pmatrix/gemini-cli-monitor | 10 hooks | LLM call observation (BeforeModel/AfterModel) | | @pmatrix/codex-monitor | 6 hooks | apply_patch direct observation + requirements.toml |

All 5 SDKs share ~/.pmatrix/HALT Kill Switch — single file activates kill switch across all monitors.

License

Apache-2.0. See LICENSE and NOTICE.

Security

See SECURITY.md for vulnerability reporting policy.

P-MATRIX Codex Monitor v0.1.0 (initial) · Phase R-7 · 2026-05-04