create-hook
Create Codex hooks. Use when the user wants to run a script or MCP tool at a Codex lifecycle event, write hooks.json, add hook scripts, or debug hook discovery and trust.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- create-hook
- description
- Create Codex hooks. Use when the user wants to run a script or MCP tool at a Codex lifecycle event, write hooks.json, add hook scripts, or debug hook discovery and trust.
03 SKILL.md 正文
Create Codex hooks
Create or update the hook files when the user asks for a hook. Do not stop at a format explanation.
Choose the scope and location
Codex discovers hooks next to active configuration layers:
- User JSON:
~/.codex/hooks.json - User TOML: inline
[hooks]tables in~/.codex/config.toml - Project JSON:
<repo>/.codex/hooks.json - Project TOML: inline
[hooks]tables in<repo>/.codex/config.toml - Plugin:
hooks/hooks.jsoninside the plugin unless its manifest overrides the path
Store related user scripts under ~/.codex/hooks/. Store project scripts under <repo>/.codex/hooks/.
Prefer one representation per config layer. If a layer has both hooks.json and inline TOML hooks, Codex merges them and warns.
Project hooks load only for trusted projects. Non-managed hooks must be reviewed and trusted before they run. Use /hooks to inspect sources, review changes, trust a definition, or disable a hook.
Supported lifecycle events
Use the narrowest event that fits:
SessionStart,SessionEndUserPromptSubmitPreToolUse,PermissionRequest,PostToolUseSubagentStart,SubagentStopPreCompact,PostCompactStop
Event names are case-sensitive.
JSON shape
A hook has an event, a matcher group, and one or more handlers:
{
"description": "Project command review hook.",
"hooks": {
"PreToolUse": [
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use.py\"",
"timeout": 30,
"statusMessage": "Checking shell command"
}
]
}
]
}
}
Do not add the old Cursor version: 1 wrapper. Keep existing unrelated hook groups intact.
Handler types
Use one of the handler types Codex runs:
commandexecutes a local command. It receives the event JSON on stdin and returns its event-specific response on stdout.mcp_toolcalls a tool on an already-connected MCP server.
prompt and agent handlers may parse, but Codex currently skips them. Do not create them.
For command hooks:
- Give scripts a valid shebang and executable permission.
- Verify every helper binary they call.
- Parse stdin defensively and emit only fields supported by that event.
- Use an explicit timeout when a stalled command would disrupt the workflow.
- Remember that matching command hooks for the same event launch concurrently.
Commands run with the session working directory. A project session may start in a subdirectory, so resolve project scripts from the Git root instead of relying on a relative path such as .codex/hooks/script.py.
MCP tool example
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "mcp_tool",
"server": "scanner",
"tool": "scan_patch",
"input": {
"path": "${tool_input.file_path}"
},
"timeout": 30
}
]
}
]
}
}
Codex expands ${field.nested} placeholders from the hook event.
Workflow
- Determine the scope, event, matcher, handler type, and desired effect.
- Read the existing hook source and preserve unrelated entries.
- Write the hook definition and any required script under the matching
.codex/hooks/directory. - Validate JSON or TOML syntax.
- Make command scripts executable and verify their dependencies.
- Open
/hooksand complete the required trust review. - Trigger the real event and check the observed result.
Before using an unfamiliar event field or response field, consult the current official Codex hooks documentation.
04 同仓库更多 Skills
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
wait-what
Stop. That last message did not land: re-pitch it.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).
to-spec
Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed.