| name | codex-compat |
| description | Generate Codex hooks.json and AGENTS.md from Claude Code hooks. Maps supported hooks directly, including Edit|Write apply_patch aliases, and keeps Stop batch checks only as fallback. Use when setting up Codex compatibility or dual-agent support. |
Codex Compatibility Layer
Codex now supports Claude-style lifecycle hooks for SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, and Stop. PreToolUse/PostToolUse matchers support Bash, MCP tool names, apply_patch, and Edit|Write aliases. Map Edit|Write hooks direct whenever possible.
What This Creates
.codex/hooks.json -- direct translation for supported Claude hooks.codex/hooks/codex-batch-check.sh -- fallback only for checks that cannot run per tool eventAGENTS.md + CLAUDE.md -- shared project rules (Codex reads AGENTS.md, Claude Code reads CLAUDE.md)- compatibility matrix -- classify hooks as
direct, direct with shim, fallback only, or unsupported
Steps
- Read
.claude/settings.json and classify every hook with the REFERENCE.md compatibility matrix.
- Generate
.codex/hooks.json:
SessionStart, UserPromptSubmit, Stop -> directPreToolUse / PostToolUse with Bash, Edit|Write, apply_patch, mcp__.* -> directPermissionRequest for Bash / MCP / apply_patch -> direct where scripts understand Codex payloads- Unsupported Claude events or handler types -> omit, document, or route to fallback only when semantics stay safe
- Copy
scripts/codex-batch-check.sh -> .codex/hooks/ only if fallback hooks are needed. chmod +x.
- Generate
AGENTS.md + CLAUDE.md from REFERENCE.md template.
Verify
