Documentation
¶
Overview ¶
Package hooks provides hook utilities for engram.
Package hooks provides hook utilities for engram.
Index ¶
- Constants
- Variables
- func EnsureWorkerRunning() (int, error)
- func GET(port int, path string) (map[string]interface{}, error)
- func GetWorkerPort() int
- func GetWorkerVersion(port int) string
- func IsPortInUse(port int) bool
- func IsWorkerRunning(port int) bool
- func KillProcessOnPort(port int) error
- func POST(port int, path string, body interface{}) (map[string]interface{}, error)
- func ProjectIDWithName(cwd string) string
- func RunHook[T any](hookName string, handler HookHandler[T])
- func RunStatuslineHook[T any](handler StatuslineHandler[T])
- func WriteError(hookName string, err error)
- func WriteResponse(hookName string, success bool)
- type BaseInput
- type HookContext
- type HookHandler
- type HookResponse
- type StatuslineHandler
Constants ¶
const ( ExitSuccess = 0 ExitFailure = 1 ExitUserMessageOnly = 3 // Display stderr as user message )
Exit codes for Claude Code hooks
const ( // DefaultWorkerPort is the default worker port. DefaultWorkerPort = 37777 // HealthCheckTimeout is the timeout for health checks (reduced from 5s for faster startup). HealthCheckTimeout = 1 * time.Second // StartupTimeout is the timeout for worker startup. StartupTimeout = 30 * time.Second )
Variables ¶
var Version = "dev"
Version is set at build time via ldflags
Functions ¶
func EnsureWorkerRunning ¶
EnsureWorkerRunning ensures the worker is running, starting it if necessary. If a worker is already running and healthy with matching version, it reuses it. If version mismatch or unhealthy, it kills the old worker and starts fresh.
func GetWorkerPort ¶
func GetWorkerPort() int
GetWorkerPort returns the worker port from environment or default.
func GetWorkerVersion ¶
GetWorkerVersion gets the version of the running worker.
func IsPortInUse ¶
IsPortInUse checks if the port is in use (regardless of health).
func IsWorkerRunning ¶
IsWorkerRunning checks if the worker is running and healthy.
func KillProcessOnPort ¶
KillProcessOnPort finds and kills the process using the given port.
func ProjectIDWithName ¶
ProjectIDWithName returns both the hash ID and the directory name for display. Format: "dirname_abc123" (name + truncated hash for human-readability)
func RunHook ¶
func RunHook[T any](hookName string, handler HookHandler[T])
RunHook executes a hook with common boilerplate handling. It handles: internal call skip, stdin reading, JSON unmarshaling, worker startup, and project ID generation.
func RunStatuslineHook ¶
func RunStatuslineHook[T any](handler StatuslineHandler[T])
RunStatuslineHook executes a statusline hook with minimal overhead. Unlike RunHook, this: - Does NOT check ENGRAM_INTERNAL (statuslines always run) - Uses GetWorkerPort() instead of EnsureWorkerRunning() (no startup) - Prints output directly to stdout (no JSON wrapping) This keeps statusline fast (<100ms requirement).
func WriteError ¶
WriteError writes an error message to stderr and exits.
func WriteResponse ¶
WriteResponse writes a hook response to stdout.
Types ¶
type BaseInput ¶
type BaseInput struct {
SessionID string `json:"session_id"`
CWD string `json:"cwd"`
PermissionMode string `json:"permission_mode"`
HookEventName string `json:"hook_event_name"`
}
BaseInput contains common fields shared by all hook inputs.
type HookContext ¶
type HookContext struct {
HookName string
Project string
SessionID string
CWD string
RawInput []byte
Port int
}
HookContext provides common context for hook handlers.
type HookHandler ¶
type HookHandler[T any] func(ctx *HookContext, input *T) (additionalContext string, err error)
HookHandler is a function that handles hook-specific logic. It receives the context and returns an optional context string and error.
type HookResponse ¶
type HookResponse struct {
Continue bool `json:"continue"`
}
HookResponse is the response sent back to Claude Code.
type StatuslineHandler ¶
StatuslineHandler is a function that handles statusline-specific logic. It receives input and port, returns formatted status string. No context injection or worker startup - just display.
Source Files