Skip to content
PopKit Documentation

Hooks

Hooks

Section titled “Hooks”

Hooks are event-driven scripts that execute at specific points in the Claude Code lifecycle. PopKit includes 23 hooks for various events.

What are Hooks?

Section titled “What are Hooks?”

Hooks in PopKit:

  • Event-driven: Triggered by specific lifecycle events
  • Portable: Use cross-platform path conventions
  • Validated: Follow JSON stdin/stdout protocol
  • Tested: Have comprehensive test coverage

Hook Events

Section titled “Hook Events”

Session Lifecycle

Section titled “Session Lifecycle”
  • SessionStart: When Claude Code session begins
  • SessionEnd: When session ends
  • SessionResume: When session is restored

Interaction Events

Section titled “Interaction Events”
  • FirstMessage: Before first user message
  • UserMessage: After each user message
  • AssistantMessage: After Claude’s response

File Events

Section titled “File Events”
  • FileCreate: When file is created
  • FileModify: When file is modified
  • FileDelete: When file is deleted

Git Events

Section titled “Git Events”
  • GitCommit: Before/after git commits
  • GitPush: Before/after git push
  • GitPR: When pull request is created

Hook Protocol

Section titled “Hook Protocol”

All hooks use a standard JSON protocol:

Input (stdin):

{
  "event": "SessionStart",
  "data": {
    "cwd": "/path/to/project",
    "timestamp": "2026-01-14T12:00:00Z"
  }
}

Output (stdout):

{
  "status": "success",
  "message": "Hook executed successfully",
  "data": {}
}

Hook Standards

Section titled “Hook Standards”

PopKit hooks follow Claude Code portability standards:

  • Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
  • Double-quoted paths for Windows compatibility
  • Forward slashes for cross-platform support
  • Python shebang: #!/usr/bin/env python3

Creating Custom Hooks

Section titled “Creating Custom Hooks”

Hooks are defined in hooks/hooks.json with:

{
  "SessionStart": {
    "type": "command",
    "command": "python \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.py\"",
    "timeout": 10000
  }
}

See the Hook Development Guide for details.

Next Steps

Section titled “Next Steps”