Codex Setup

Pushary connects to Codex through MCP and native Codex hooks. The MCP server gives Codex access to push notification tools. The hooks run Pushary's policy engine on Codex tool calls: phone approvals, always-deny rules, the kill switch, task titles, and session tracking.

Setup wizard

npx @pushary/agent-hooks setup

Select "Codex". The wizard will:

• Install @pushary/agent-hooks globally
• Add the Pushary MCP server via codex mcp add
• Write six hook entries to ~/.codex/hooks.json
• Remove the legacy notify handler from ~/.codex/config.toml if present
• Save your API key to your shell profile

Trust the hooks

Codex does not run hooks until you trust them. This is a one-time step:

1. Open Codex
2. Run /hooks
3. Review the Pushary entries and trust them

All six entries run the same pushary-codex-hook command, so there is one command to review. Upgrades do not re-prompt because the trust hash is tied to the hook definition, and the command string stays stable across versions.

For CI environments where the trust prompt cannot be answered, Codex supports --dangerously-bypass-hook-trust. Use it only in CI.

What each hook does

Capability parity with Claude Code

What hooks cannot intercept yet

Codex hook interception is incomplete by OpenAI's own documentation: unified_exec and non-shell tools are not yet intercepted. Treat enforcement on Codex as a guardrail, not a security boundary. Policies and the kill switch apply to shell commands and apply_patch calls, which covers most of what an agent does, but not everything.

Manual setup

If you prefer not to use the wizard:

MCP server

codex mcp add pushary --url https://pushary.com/api/mcp/mcp --bearer-token-env-var PUSHARY_API_KEY

Set your API key in your shell profile (~/.zshrc or ~/.bashrc):

export PUSHARY_API_KEY="pk_xxx.xxx"

Hooks

Install the hooks package globally:

npm install -g @pushary/agent-hooks

Add the entries to ~/.codex/hooks.json. Replace the command with the output of which pushary-codex-hook and use the same path in every entry:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash|apply_patch",
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 180, "statusMessage": "Waiting for your phone" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|apply_patch",
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 180, "statusMessage": "Checking Pushary policy" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|apply_patch",
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 10 }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 10 }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 10 }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          { "type": "command", "command": "/path/to/pushary-codex-hook", "timeout": 10 }
        ]
      }
    ]
  }
}

Then complete the trust step above.

MCP tools

Once connected, Codex can use these tools:

Legacy notify handler (deprecated)

Older Codex versions without hook support fall back to the pushary-codex notify handler in ~/.codex/config.toml. It captures turn completions and approval requests, but has no policy engine, no kill switch, and no session tracking. The setup wizard installs it automatically only when your Codex version predates hooks, and removes it once you upgrade and re-run setup.