# Codex

> Set up Comity hooks and MCP for OpenAI Codex, including the hook approval step.

Codex gets the same integration as Claude Code: hooks on session start, prompts, edits (`apply_patch`) and shell commands, plus the Comity MCP server.

## Set up

```sh
cd your-repo
comity init --tools codex
git add .codex/hooks.json .codex/config.toml
git commit -m "Set up Comity for coding agents"
```

Then in Codex:

1. Trust the project when Codex asks.
2. Open `/hooks` and approve the `comity` hooks.

> [!IMPORTANT]
> Codex skips project hooks until you approve them in `/hooks`. Until then Comity sees nothing from that Codex session: no briefings, no warnings, no blocks. `comity doctor` can't see the approval state, so check `/hooks` yourself.

## What init writes

### `.codex/hooks.json`

Same six events as Claude Code. Each handler has a POSIX `command` and a `commandWindows` variant, because Codex runs hook commands through Windows PowerShell on Windows. Shown for one event; the others differ only in event name, matcher and timeout.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "apply_patch|Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool codex --event PreToolUse",
            "commandWindows": "$c = Get-Command comity -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1; if (-not $c) { exit 0 }; & $c.Source hook --tool codex --event PreToolUse",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

| Event | Matcher | Timeout (s) |
|---|---|---|
| `SessionStart` | | 5 |
| `UserPromptSubmit` | | 5 |
| `PreToolUse` | `apply_patch\|Edit\|Write\|Bash` | 5 |
| `PostToolUse` | `apply_patch\|Edit\|Write\|Bash` | 10 |
| `Stop` | | 10 |
| `SessionEnd` | | 3 |

The Windows command resolves `comity.cmd`/`comity.exe` directly and skips the npm `comity.ps1` shim, which PowerShell's default execution policy refuses to run. Both variants exit quietly when the CLI isn't installed.

### `.codex/config.toml`

```toml
[mcp_servers.comity]
url = "https://api.comity.so/mcp"
http_headers_helper = "comity mcp-headers"
```

Codex runs `comity mcp-headers` at connect time to get the `Authorization` header from `COMITY_TOKEN` or your login. No token is written. Other tables in the file, including your own `[mcp_servers.comity.tools.*]` subtables, are kept.

## What your agent sees

- **Session start and each prompt**: the briefing as added context.
- **Before an edit or shell command**: a block denies the call with Comity's reason. Warnings are added as context right away (Codex supports `additionalContext` on `PreToolUse`).
- **After an edit or shell command**: new conflicts, messages, answers and arrival notices.

Codex reads only the first 512 characters of an MCP server's instructions; Comity puts the essential rules first for that reason. Use [agent instructions](/docs/agents/best-practices) in `AGENTS.md` to reinforce them.

## Verify

```sh
comity doctor
```

Expect `codex hooks  all 6 events installed (Codex runs them only after you approve them in /hooks)` and `codex mcp  configured in …/.codex/config.toml`. In Codex, `/mcp` should list `comity`.