hooks.md

Hooks

Codexkit ships optional helper scripts in .codex/hooks/. They are useful for logging, post-processing, and lightweight workflow reminders.

Supported Hook Events

Codexkit documents the official Codex hook surface that matters for this repo:

Event	Notes
SessionStart	Fires on startup or resume; can inject extra developer context
PreToolUse	Currently matches only Bash
PostToolUse	Typically used with Bash; matcher should align with tool names emitted by Codex runtime
UserPromptSubmit	Runs before a prompt is sent
Stop	Runs at turn stop; expects JSON on stdout

Hooks are a Codex feature flag. Codexkit enables them in shipped project configs because DCG and startup context depend on .codex/hooks.json; users can still disable them by setting [features].hooks = false.

This repo currently wires these native events in .codex/hooks.json:

• PreToolUse (matcher Bash) → pre_tool_use_dcg.sh — DCG real-time destructive command guard
• SessionStart (matcher startup|resume) → session_start.sh — inject startup context
• PostToolUse (matcher Bash) → after_tool_use.sh — file change detection
• UserPromptSubmit → user_prompt_submit.sh — inject flywheel context (active beads, ready count, session state)
• Stop → stop.sh — end-of-session checkpoint

after_agent.sh, pre_commit.sh, and post_commit.sh remain helper/utility scripts in the repo, but they are not wired as native Codex hook events.

What Hooks Are Good For

• Logging agent responses or tool usage
• Triggering local notifications
• Appending worklog breadcrumbs
• Lightweight auditing of tool behavior
• Reminding the operator to update the right memory artifact after meaningful work

What Hooks Are Not For

Do not use hooks to bootstrap MCP credentials or project env files. Do not use hooks as the primary control plane for session start/end lifecycle. Do not let hooks write durable project state automatically into the wrong file.

MCP servers need their auth variables available before codex starts and before MCP initialization happens. In Codexkit, the supported path is:

1. Put secrets in .codex/.env
2. Start Codex with codexkit run

codexkit run loads .codex/.env before codex launches.

Configuration

Project installs enable hooks in .codex/config.toml and define handlers in .codex/hooks.json:

[features]
hooks = true

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".../.codex/hooks/pre_tool_use_dcg.sh",
            "statusMessage": "DCG: Checking command safety"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [{ "type": "command", "command": ".../.codex/hooks/session_start.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".../.codex/hooks/after_tool_use.sh" }]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".../.codex/hooks/user_prompt_submit.sh",
            "statusMessage": "Injecting flywheel context"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": ".../.codex/hooks/stop.sh" }]
      }
    ]
  }
}

Script Requirements

• Scripts must be executable.
• Scripts should stay fast and side-effect light.
• Non-zero exit codes should be treated as hook failures, not as the primary control plane for Codex startup.

Memory Boundaries

If hooks touch memory-related files, keep the boundaries strict:

• .codex/context/worklog.md for lightweight milestone breadcrumbs
• .codex/context/session-context.md for explicit pause/resume stop points
• .codex/memory/project/state.md for deliberate durable state and blockers
• .codex/context/decision-log.md only for true decisions with rationale

Hooks should prefer logging or reminding over silently mutating durable state.

Optional Extensions

Memory Search in Hooks

The derived memory index can be queried from hooks for context-aware automation. However, this adds latency and should only be used when the benefit justifies the cost:

# Example: surface related prior work when entering a new module
# Add to a custom after_tool_use.sh extension:
result=$(bash .codex/scripts/memory_search.sh "relevant query" --limit 2 2>/dev/null)
if [[ -n "$result" ]]; then
  echo "Related prior context found — run /prompts:search for details"
fi

Keep hook extensions lightweight. The default hooks intentionally avoid expensive operations.