Stop Codex from force-pushing main or editing your .env, and make it run the tests before it says it's done.
10 ready hooks for OpenAI Codex (CLI, IDE extension and app), an installer, a linter for hooks.json and inline [hooks], and a simulator that checks every hook answer against the Codex output contract. Python 3.9+, standard library only, works offline.
The screenshot is real output from the kit’s own commands. Tested from a fresh download of this exact zip: ./run_tests.sh ran 40 tests OK on Python 3.13 and 3.10.
| Hook id | Event (matcher) | What it does |
|---|---|---|
| block-dangerous-bash | PreToolUse (^Bash$) | Denies rm -rf / ~ *, force pushes to main/master/production, git reset --hard, git clean -fdx, curl | sh, chmod 777, mkfs/dd to disks, DROP DATABASE from a CLI, terraform destroy, kubectl delete namespace. Normal commands (rm -rf node_modules, force push to a feature branch) pass. |
| protect-files | PreToolUse (^apply_patch$|^Bash$) | Stops edits to .env*, keys, secrets/, .git/ and the hooks themselves, through apply_patch (Add/Update/Delete/Move) or shell writes (>, >>, sed -i, tee, cp, mv, rm). .env.example stays editable. |
| mcp-guard | PreToolUse (^mcp__) | Allowlist / denylist for MCP tools (mcp__github__*, mcp__*__delete_*) and a secret check on tool arguments. |
| approve-safe-commands | PermissionRequest (^Bash$) | Answers approval prompts for read-only commands you list (git status, npm test, rg ...), denies dangerous ones, stays silent for the rest. Rejects anything with redirects, $( ), backticks or sudo. |
| scan-prompt-secrets | UserPromptSubmit | Blocks prompts that contain OpenAI, Anthropic, AWS, GitHub, Slack, Stripe or Google keys, JWTs or private keys, without echoing the secret. |
| session-context | SessionStart (startup|resume|compact) | Hands Codex the branch, uncommitted files, last 5 commits and .codex/notes.md, capped in size. |
| subagent-brief | SubagentStart | Gives every subagent the first lines of AGENTS.md, the protected paths and a "report changed files" instruction. |
| stop-require-tests | Stop | If code changed, runs your tests before Codex finishes; on failure returns decision: block so Codex keeps fixing. Never loops (stop_hook_active). Always prints JSON, as Stop requires. |
| precompact-notes | PreCompact (manual|auto) | Writes a checkpoint (branch, diff stat) to .codex/notes.md before compaction; session-context feeds it back after. |
| audit-log | PostToolUse (all, async) | One JSON line per tool call in .codex/logs/audit.jsonl, secrets redacted. Runs in the background. |
Also: templates/ (hooks.json for the strict, balanced, guardrails and logging profiles, a user-level ~/.codex/hooks.json, and the inline TOML form), tools/codex_hooks_lint.py, tools/simulate.py, tools/install.py, examples/ (a broken setup and two buggy hooks to learn from), docs/events.md (event and output cheat sheet).
./tools/demo.shpython3 tools/install.py /path/to/repo # balanced profile (7 hooks)
python3 tools/install.py /path/to/repo --profile strict # all 10
python3 tools/install.py /path/to/repo --only block-dangerous-bash,protect-files
python3 tools/install.py --user --profile guardrails # ~/.codex/hooks.json for every project
python3 tools/install.py --toml --profile balanced # print inline [hooks] tables for config.tomlThe installer copies the scripts to .codex/hooks/, merges our matcher groups into .codex/hooks.json (your existing hooks stay) and writes hooks-config.json once. Commands resolve from the git root ($(git rev-parse --show-toplevel)), so they work when Codex starts in a subdirectory.
Then trust them. Codex skips new or changed non-managed hooks until you review them: start Codex in the repo, run /hooks, review and trust each one (in the app: Settings > Hooks). Project hooks load only when the project's .codex/ layer is trusted.
Edit .codex/hooks/hooks-config.json: protected_paths, allowed_env_examples, protected_branches, mcp_allow, mcp_deny, safe_commands, test_command (empty = auto-detect npm / pytest / unittest / go / cargo), test_timeout, notes_file, audit_log, context_limit_chars. Changing a hook script changes its hash, so Codex asks you to review it again.
python3 tools/codex_hooks_lint.py .codex # hooks.json + config.toml in a layer
python3 tools/codex_hooks_lint.py ~/.codex/config.toml --jsonIt catches: misspelled or foreign events (Cursor/Claude names), invalid matcher regexes, matchers on events that ignore them, matcher values that never occur (SessionStart sources, compaction triggers), tool names Codex doesn't use (Shell, run_terminal_cmd, Read), prompt/agent handlers (skipped by Codex), mcp_tool without server/tool or on SessionEnd, non-integer timeouts, SessionEnd/Interrupt timeouts over 3 s, async on events that must block, additionalContextLimit where it's ignored or set to 0, relative .codex/hooks/ paths, missing scripts, secrets in commands, the deprecated codex_hooks feature key, hooks turned off, and hooks.json + inline [hooks] in the same layer. Exit 1 on errors, so it fits CI.
python3 tools/simulate.py hooks/block_dangerous_bash.py PreToolUse --tool Bash --command "git reset --hard"
python3 tools/simulate.py "node my-hook.js" Stop --stop-hook-active
python3 tools/simulate.py my_hook.py PostToolUse --tool mcp__fs__write --tool-input '{"path":"a"}' --jsonThe simulator builds the event JSON Codex sends, runs the hook, and tells you what Codex would do (deny, rewrite, block, continue-turn, context...) plus contract problems: plain text from Stop, continue/stopReason from PreToolUse, permissionDecision: "ask", updatedInput without allow, reserved PermissionRequest fields, wrong hookEventName, exit 2 on events that can't block.
./run_tests.sh runs 40 tests (standard library unittest): 25 dangerous and 14 safe commands, protected paths through apply_patch and shell, prompt secrets with no false positives on normal text, MCP allow/deny, approval decisions, session context and caps, the Stop hook in a real temporary git repo (fail, pass, timeout, no loop), audit redaction, the linter on the broken example (every rule), clean templates, installer merge/idempotence/dry-run, TOML output, and the output contract rules. Tested on Python 3.13 and 3.10.
Zip, 51 KB, v1.0, 40 files. You may use and modify this kit for your own work and for clients you serve, including paid client work. Not affiliated with or endorsed by OpenAI.
10 ready OpenAI Codex hooks: block rm -rf and force pushes, protect .env, MCP allowlist, run tests on Stop, plus a hooks.json linter and simulator.
9 ready OpenAI Codex config.toml templates (profiles, MCP servers, providers, CI) and a checker that validates yours against the published schema.
View Codex Config Kit: config.toml Templates + Schema CheckerValidate and migrate A2A Agent Cards to v1.0: spec checker, v0.3 migrator, 8 example cards, live endpoint checker and a reference agent. Python, no deps.
View A2A Agent Card Kit: v1.0 Validator, Migrator, Templates + Test AgentFree A2A Agent Card validator: checks agent-card.json against A2A Protocol v1.0, flags v0.3 leftovers with fixes, works on files or live URLs. Python.
View Free A2A Agent Card Validator (A2A Protocol v1.0)Short weekly digest of new x402 + MCP tools and free kits, including the MCP OAuth Checker. No spam, unsubscribe any time.