Codex hook json sessionstart

Codex Hook JSON SessionStart

Use When

• A Codex hook is meant to inject reminder context at session start.
• The hook prints plain text copied from a Claude hook.
• hooks.json points at a shell script but Codex does not receive the reminder.
• You are renaming or replacing a hook under ~/.codex/hooks/.

Failure Mechanism

Claude hooks can inject visible plain text. Codex SessionStart hooks should emit structured JSON so Codex can place the reminder in additionalContext. A copied Claude hook may execute successfully while providing no usable Codex context.

Procedure

1. Read ~/.codex/hooks.json and the referenced hook script.
2. Make the command point at a real executable under ~/.codex/hooks/.
3. Have the script emit JSON with:
   • hookSpecificOutput.hookEventName set to SessionStart
   • reminder text in hookSpecificOutput.additionalContext
4. Keep the hook output short. It should remind Codex to evaluate a skill, not duplicate the whole skill.

Example hook body:

#!/bin/bash
cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "[codexception]\nAfter completing this user request, evaluate whether the work produced reusable knowledge worth preserving as a Codex skill."
  }
}
EOF

Verification

• ruby -rjson -e 'JSON.parse(File.read(File.expand_path("~/.codex/hooks.json")))'
• ruby -rjson -e 'JSON.parse(~/.codex/hooks/codexception-activator.sh)'
• ~/.codex/claude-bridge/validate.sh still passes if bridge-managed files are present.

High-Risk Actions

• Do not paste the full skill into the hook output.
• Do not leave stale hook paths after renaming a skill or script.
• Do not use a Claude plain-text activation banner as the Codex hook body.