Codex
Wire the hooks into Codex and trust them.
Codex runs the same hooks as Claude Code. Every entry runs the skills CLI through the AGENTS_DIR link. Whenever ~/.codex (or CODEX_HOME) exists, the installer writes the entries below to its hooks.json. Trust new or replaced entries once. The installer replaces both owned comment and dash shims with one skills hook post-tool-use command. If you wired the shims yourself, replace both with that command.
It also replaces the owned commit guard and reply guard shell hooks with skills hook pre-tool-use and skills hook stop. If you wired either yourself, replace it with its CLI command. Do not add the CLI command beside it.
Trust the Hooks
Codex records trust per hook definition. Open codex, run /hooks, and trust the new entries once. A later install run that adds nothing leaves the file untouched, so the trust holds.
What the Installer Writes
Every entry runs the skills CLI by absolute path under AGENTS_DIR (Configuration). With a home of /Users/you, the entries are:
{
"hooks": {
"SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "/Users/you/.agents/skills/playbook/bin/skills hook session-start" }] }],
"PreToolUse": [{ "matcher": "^Bash$", "hooks": [{ "type": "command", "command": "/Users/you/.agents/skills/playbook/bin/skills hook pre-tool-use" }] }],
"PostToolUse": [{ "matcher": "^(Bash|apply_patch)$", "hooks": [
{ "type": "command", "command": "/Users/you/.agents/skills/playbook/bin/skills hook post-tool-use" } ] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "/Users/you/.agents/skills/playbook/bin/skills hook stop" }] }]
}
}- The PostToolUse entry matches
Bashas well asapply_patch, because Codex usually applies a patch by runningapply_patchthrough the shell, and hooks see that call asBash. The CLI checks only shell commands that apply a patch and stays silent on every other command. - Missing entries are added. An entry this repository shipped for a retired hook is switched to its replacement in place and needs trusting again. A personal entry is left alone. The old comment and dash entries are the exception: they sat under
^(Edit|MultiEdit|Write)$, which Codex never fires for a shell patch, so they are dropped and the CLI entry is added in a group of its own. - A run that adds or replaces an entry rewrites the file with two space indent, keeping its mode and group, and copying its extended attributes where the system allows. Whether ACLs survive depends on the platform. A run with nothing to change leaves the file untouched.
- A file that is not valid JSON is left alone, and the run prints the entries to add by hand.
- Deleting a skills entry does not stick, since the next install adds it back. To turn the hooks off, set
AGENT_HOOKS=0(Configuration). It turns off every hook but the commit guard, which skips only its comment sweep.
What each hook does, and when it stays silent, is on the Hooks pages.
Invoking Skills
Every skill whose SKILL.md sets disable-model-invocation: true also carries agents/openai.yaml, which sets allow_implicit_invocation: false. Codex keeps those skills out of the model's skill listing, so describing what one does in a prompt no longer opens it. Invoke one as $name, such as $architect, the way Claude Code takes /architect. The installer links each skill directory whole, so the file reaches ~/.codex/skills with the rest of the skill.
Rules
With AGENT_RULES set (Deny rules), the installer also writes rules/skills.rules under ~/.codex (or CODEX_HOME). Codex reads every .rules file there at startup, so restart Codex after a run that changes it. The installer owns the whole file: its first line is # Written by skills install. Edits are replaced on the next run., and a skills.rules without that line is left alone, with the reason in the output. No other rules file is touched, default.rules included.
Each guardrail group becomes prefix_rule entries at the level you chose: deny writes forbidden and ask writes prompt. Spellings that differ in one word share a rule, so the publishing group in hands-off mode reads:
# publishing: Commit, push or open a PR
prefix_rule(pattern = ["git", ["commit", "push"]], decision = "forbidden", justification = "Commit, push or open a PR")- A Codex rule matches the start of a command only, so an entry with a wildcard before its end (
git push * --force), an Edit path, or askills.*key has no rule. The output names every entry it skipped. The commit guard hook still covers force pushes. - Allow groups are never written, since a Codex allow runs the command outside the sandbox.
- The comment group follows the commit guard in
hooks.json: once that hook is wired, prs mode writes no comment rule. - A change that weakens a rule follows the same terminal rule as Claude settings: an agent run leaves it and names it, and you apply it by rerunning
./install.shin your own terminal. - When
codexis on PATH, the new file is checked withcodex execpolicy checkbefore it replaces the old one. A file that fails the check is not written. To check it yourself:codex execpolicy check --rules ~/.codex/rules/skills.rules -- gh pr merge 7.
The same as invalid JSON, with the entries printed for you: a hooks.json that is a directory, a dangling symlink, not UTF-8, not readable, not writable, owned by another user, hard linked, or whose hooks key or event lists are not the shape Codex expects.
A personal retired hook with an entry in hooks.json keeps its file and entry. The installer skips its CLI replacement and the output says so.
If the playbook link points elsewhere, all four CLI entries are skipped and the old entries stay. If Bun is missing, SessionStart, PostToolUse and Stop are skipped the same way, but PreToolUse still gets the commit guard: it denies every shell command until Bun is installed, and the install output says so. Bun is found on PATH, then at ~/.bun/bin/bun, /opt/homebrew/bin/bun, or /usr/local/bin/bun.
If hooks.json already runs a personal session-brief.sh in the SessionStart event, the installer keeps that entry and skips the CLI entry to avoid a doubled brief. This also applies when a shallow clone or tarball cannot recognise an old copy as shipped. A personal file without an entry does not block the CLI entry.
The same rule applies to a personal retired commit guard in PreToolUse and a personal retired reply guard in Stop. Its file and entry stay, and the CLI entry is skipped. A personal file without an entry does not block the CLI entry.