hooks-guide

Route to Reference

flowchart TD
    Start([What do you need?]) --> Q1{Which platform?}
    Q1 -->|Claude Code| Q2{Inline agent hooks<br>hooks/mcpServers/skills/memory?}
    Q1 -->|OpenAI Codex plugin| OpenAI["Read references/openai-codex.md"]
    Q1 -->|GitHub Copilot| Copilot["Read references/github-copilot.md"]
    Q1 -->|Cursor, Windsurf, Amp<br>or coverage gaps| Coverage["Read references/platform-coverage.md"]

    Q2 -->|Yes — agent frontmatter| Agent["Read references/inline-agent-hooks.md"]
    Q2 -->|No — project or global hooks| Q3{Interacts with session data?<br>costs, workloads, duration, tracking}

    Q3 -->|Yes — reading or writing<br>session logs or token data| SessionSchema["Load references/claude-session-log-schema-reference.md<br>before writing any code"]
    Q3 -->|No| Q4{Which language?}

    SessionSchema --> Q4

    Q4 -->|Node.js| CJS["Read references/hooks-nodejs-extension.md"]
    Q4 -->|Python| Py["Read references/hooks-python.md"]
    Q4 -->|Not sure / both| Both["Read references/hooks-nodejs-extension.md<br>then references/hooks-python.md"]

    Agent --> CC["Also read references/claude-code.md<br>for full event schema"]
    Q4 --> Schema["Cross-platform concepts:<br>references/common-schema.md"]
    Copilot --> Schema
    Coverage --> Schema

Specialist Skills

For deeper Claude Code coverage, these focused skills are available:

• hooks-core-reference — Hook system fundamentals: events, configuration, matchers, environment variables, execution, security, debugging. Activate /plugin-creator:hooks-core-reference for configuration and troubleshooting.
• hooks-io-api — JSON input/output API: what data hooks receive via stdin and what JSON they return to control Claude. Activate /plugin-creator:hooks-io-api when writing hook scripts that process input or produce JSON output.
• hooks-patterns — Recipes and working examples: plugin hooks, frontmatter hooks, prompt-based hooks, complete code examples in Python/Node.js. Activate /plugin-creator:hooks-patterns for implementation patterns and examples.

Reference Files

• references/common-schema.md — shared concepts, cross-platform comparison, JSON I/O, exit codes
• references/claude-code.md — Claude Code hooks full reference (events, matchers, configuration)
• references/openai-codex.md — OpenAI plugin hook discovery, trust, execution, and platform boundaries
• references/inline-agent-hooks.md — hooks, mcpServers, skills, and memory in agent frontmatter
• references/github-copilot.md — GitHub Copilot coding agent hooks
• references/hooks-nodejs-extension.md — Node.js authoring guide: extension rules (.mjs/.cjs), templates, anti-patterns
• references/hooks-python.md — Python authoring guide and templates
• references/best-practices.md — cross-platform conventions and anti-patterns
• references/platform-coverage.md — known platforms, fetch URLs, coverage status
• references/hooks-lifecycle.png — visual diagram of the full hook event sequence
• references/claude-session-log-schema-reference.md — verified schema for Claude Code session JSONL logs: file locations, record structure, tool_use/tool_result pairing, usage fields, observed response sizes. Load when creating or modifying hooks that interact with session data for costs, workloads, duration, or tracking.

Refresh Docs

Re-fetch all platform docs and run the script's focused single-reference transform on each:

bash plugins/plugin-creator/skills/hooks-guide/scripts/fetch-and-transform-hooks-docs.sh

This updates reference files from official sources. Run when upstream docs change.

Sources

• Claude Code hooks: https://code.claude.com/docs/en/hooks.md (accessed 2026-09-24)
• Claude Code hooks guide: https://code.claude.com/docs/en/hooks-guide.md (accessed 2026-09-24)
• Claude Code agent frontmatter: https://code.claude.com/docs/en/sub-agents.md (accessed 2026-09-24)
• OpenAI plugin hooks: https://developers.openai.com/plugins/build/plugins.md and https://learn.chatgpt.com/docs/hooks (accessed 2026-09-24)
• GitHub Copilot coding agent: https://docs.github.com/en/copilot/using-github-copilot/using-claude-as-your-copilot-llm (accessed 2026-02-27)