hook

Documentation

Overview

Package hook provides types and utilities for handling Claude Code hook events. For more information about Claude Code hooks, see: https://docs.anthropic.com/en/docs/claude-code/hooks

Package hook provides unified handling for both Claude Code and Codex hook events

Index

• type CodexNotifyEvent
  • func ParseCodexNotifyEvent(r io.Reader) (*CodexNotifyEvent, error)
  • func ReadCodexNotifyEvent() (*CodexNotifyEvent, error)
• type CursorAfterAgentResponseEvent
• type CursorBeforeSubmitPromptEvent
• type CursorHookEvent
• type CursorSessionStartEvent
• type CursorStopEvent
• type HookEvent
  • func ParseHookEvent(r io.Reader) (*HookEvent, error)
  • func ReadHookEvent() (*HookEvent, error)
• type NotificationEvent
  • func ParseNotificationEvent(r io.Reader) (*NotificationEvent, error)
  • func ReadNotificationEvent() (*NotificationEvent, error)
• type PostToolUseEvent
• type PreCompactEvent
• type PreToolUseEvent
• type SessionEndEvent
  • func ParseSessionEndEvent(r io.Reader) (*SessionEndEvent, error)
  • func ReadSessionEndEvent() (*SessionEndEvent, error)
• type SessionStartEvent
  • func ParseSessionStartEvent(r io.Reader) (*SessionStartEvent, error)
  • func ReadSessionStartEvent() (*SessionStartEvent, error)
• type StopEvent
  • func ParseStopEvent(r io.Reader) (*StopEvent, error)
  • func ReadStopEvent() (*StopEvent, error)
• type UnifiedHookEvent
  • func DetectAndParse(r io.Reader) (*UnifiedHookEvent, error)
  • func (e *UnifiedHookEvent) GetClaudeCodeEvent() (interface{}, bool)
  • func (e *UnifiedHookEvent) GetCodexEvent() (*CodexNotifyEvent, bool)
  • func (e *UnifiedHookEvent) GetCursorEvent() (interface{}, bool)
  • func (e *UnifiedHookEvent) IsClaudeCode() bool
  • func (e *UnifiedHookEvent) IsCodex() bool
  • func (e *UnifiedHookEvent) IsCursor() bool
• type UserPromptSubmitEvent
  • func ParseUserPromptSubmitEvent(r io.Reader) (*UserPromptSubmitEvent, error)
  • func ReadUserPromptSubmitEvent() (*UserPromptSubmitEvent, error)

Types

type CodexNotifyEvent

type CodexNotifyEvent struct {
	Type                 string   `json:"type"`                   // "agent-turn-complete"
	ThreadID             string   `json:"thread-id"`              // UUID of the thread
	TurnID               string   `json:"turn-id"`                // Turn number (string from Codex)
	CWD                  string   `json:"cwd"`                    // Current working directory
	InputMessages        []string `json:"input-messages"`         // User's input messages
	LastAssistantMessage string   `json:"last-assistant-message"` // Model's final response
}

CodexNotifyEvent represents the Codex notify hook event See: https://github.com/openai/codex/blob/main/docs/config.md

func ParseCodexNotifyEvent

func ParseCodexNotifyEvent(r io.Reader) (*CodexNotifyEvent, error)

ParseCodexNotifyEvent reads and parses Codex notify event from stdin

func ReadCodexNotifyEvent

func ReadCodexNotifyEvent() (*CodexNotifyEvent, error)

ReadCodexNotifyEvent is a convenience function to read Codex notify event from stdin

type CursorAfterAgentResponseEvent

type CursorAfterAgentResponseEvent struct {
	CursorHookEvent
	Text string `json:"text"` // The final AI response text
}

CursorAfterAgentResponseEvent represents Cursor's afterAgentResponse hook event This is the recommended hook for voice synthesis as it provides the AI response directly

type CursorBeforeSubmitPromptEvent

type CursorBeforeSubmitPromptEvent struct {
	CursorHookEvent
	Prompt string `json:"prompt"`
}

CursorBeforeSubmitPromptEvent represents Cursor's beforeSubmitPrompt hook event

type CursorHookEvent

type CursorHookEvent struct {
	ConversationID string   `json:"conversation_id"`
	GenerationID   string   `json:"generation_id"`
	Model          string   `json:"model"`
	HookEventName  string   `json:"hook_event_name"`
	CursorVersion  string   `json:"cursor_version"`
	WorkspaceRoots []string `json:"workspace_roots"`
	UserEmail      string   `json:"user_email,omitempty"`
	TranscriptPath string   `json:"transcript_path,omitempty"`
}

CursorHookEvent represents the common hook event data from Cursor See: https://cursor.com/docs/agent/hooks Note: Cursor uses conversation_id instead of session_id, and camelCase event names

type CursorSessionStartEvent

type CursorSessionStartEvent struct {
	CursorHookEvent
}

CursorSessionStartEvent represents Cursor's sessionStart hook event

type CursorStopEvent

type CursorStopEvent struct {
	CursorHookEvent
	Status    string `json:"status,omitempty"` // completed/aborted/error
	LoopCount int    `json:"loop_count,omitempty"`
}

CursorStopEvent represents Cursor's stop hook event

type HookEvent

type HookEvent struct {
	SessionID      string `json:"session_id"`
	TranscriptPath string `json:"transcript_path"`
	CWD            string `json:"cwd,omitempty"`
	HookEventName  string `json:"hook_event_name"`
}

HookEvent represents the common hook event data from Claude Code

func ParseHookEvent

func ParseHookEvent(r io.Reader) (*HookEvent, error)

ParseHookEvent reads and parses the hook event from stdin

func ReadHookEvent

func ReadHookEvent() (*HookEvent, error)

ReadHookEvent is a convenience function to read hook event from stdin

type NotificationEvent

type NotificationEvent struct {
	HookEvent
	Message string `json:"message"`
}

NotificationEvent represents the Notification hook event

func ParseNotificationEvent

func ParseNotificationEvent(r io.Reader) (*NotificationEvent, error)

ParseNotificationEvent reads and parses Notification event from stdin

func ReadNotificationEvent

func ReadNotificationEvent() (*NotificationEvent, error)

ReadNotificationEvent is a convenience function to read Notification event from stdin

type PostToolUseEvent

type PostToolUseEvent struct {
	HookEvent
	ToolName   string                 `json:"tool_name"`
	ToolResult map[string]interface{} `json:"tool_result,omitempty"`
}

PostToolUseEvent represents the PostToolUse hook event

type PreCompactEvent

type PreCompactEvent struct {
	HookEvent
	CompactMode string `json:"compact_mode"` // "manual" or "auto"
}

PreCompactEvent represents the PreCompact hook event

type PreToolUseEvent

type PreToolUseEvent struct {
	HookEvent
	ToolName   string                 `json:"tool_name"`
	ToolParams map[string]interface{} `json:"tool_params,omitempty"`
}

PreToolUseEvent represents the PreToolUse hook event

type SessionEndEvent

type SessionEndEvent struct {
	HookEvent
}

SessionEndEvent represents the SessionEnd hook event Triggered when a Claude Code session ends

func ParseSessionEndEvent

func ParseSessionEndEvent(r io.Reader) (*SessionEndEvent, error)

ParseSessionEndEvent reads and parses SessionEnd event from stdin

func ReadSessionEndEvent

func ReadSessionEndEvent() (*SessionEndEvent, error)

ReadSessionEndEvent is a convenience function to read SessionEnd event from stdin

type SessionStartEvent

type SessionStartEvent struct {
	HookEvent
}

SessionStartEvent represents the SessionStart hook event Triggered when a Claude Code session starts or resumes

func ParseSessionStartEvent

func ParseSessionStartEvent(r io.Reader) (*SessionStartEvent, error)

ParseSessionStartEvent reads and parses SessionStart event from stdin

func ReadSessionStartEvent

func ReadSessionStartEvent() (*SessionStartEvent, error)

ReadSessionStartEvent is a convenience function to read SessionStart event from stdin

type StopEvent

type StopEvent struct {
	HookEvent
	StopHookActive bool `json:"stop_hook_active,omitempty"`
}

StopEvent represents the Stop/SubagentStop hook event

func ParseStopEvent

func ParseStopEvent(r io.Reader) (*StopEvent, error)

ParseStopEvent reads and parses Stop event from stdin

func ReadStopEvent

func ReadStopEvent() (*StopEvent, error)

ReadStopEvent is a convenience function to read Stop event from stdin

type UnifiedHookEvent

type UnifiedHookEvent struct {
	Source     string      // "claude-code", "codex", or "cursor"
	SessionID  string      // Session/Thread/Conversation identifier
	CWD        string      // Current working directory
	EventType  string      // Event type (e.g., "UserPromptSubmit", "agent-turn-complete", "sessionStart")
	UserInput  []string    // User's input messages
	AIResponse string      // AI's response message
	RawEvent   interface{} // Original event for type-specific handling
}

UnifiedHookEvent represents a normalized hook event that works for Claude Code, Codex, and Cursor

func DetectAndParse

func DetectAndParse(r io.Reader) (*UnifiedHookEvent, error)

DetectAndParse automatically detects the hook source and parses the event

func (*UnifiedHookEvent) GetClaudeCodeEvent

func (e *UnifiedHookEvent) GetClaudeCodeEvent() (interface{}, bool)

GetClaudeCodeEvent returns the underlying Claude Code event if available

func (*UnifiedHookEvent) GetCodexEvent

func (e *UnifiedHookEvent) GetCodexEvent() (*CodexNotifyEvent, bool)

GetCodexEvent returns the underlying Codex event if available

func (*UnifiedHookEvent) GetCursorEvent

func (e *UnifiedHookEvent) GetCursorEvent() (interface{}, bool)

GetCursorEvent returns the underlying Cursor event if available

func (*UnifiedHookEvent) IsClaudeCode

func (e *UnifiedHookEvent) IsClaudeCode() bool

IsClaudeCode returns true if the event is from Claude Code

func (*UnifiedHookEvent) IsCodex

func (e *UnifiedHookEvent) IsCodex() bool

IsCodex returns true if the event is from Codex

func (*UnifiedHookEvent) IsCursor

func (e *UnifiedHookEvent) IsCursor() bool

IsCursor returns true if the event is from Cursor

type UserPromptSubmitEvent

type UserPromptSubmitEvent struct {
	HookEvent
	Prompt string `json:"prompt"`
}

UserPromptSubmitEvent represents the UserPromptSubmit hook event

func ParseUserPromptSubmitEvent

func ParseUserPromptSubmitEvent(r io.Reader) (*UserPromptSubmitEvent, error)

ParseUserPromptSubmitEvent reads and parses UserPromptSubmit event from stdin

func ReadUserPromptSubmitEvent

func ReadUserPromptSubmitEvent() (*UserPromptSubmitEvent, error)

ReadUserPromptSubmitEvent is a convenience function to read UserPromptSubmit event from stdin