hooks

OmniConfig Hooks

The hooks package provides a unified interface for managing automation/lifecycle hooks across multiple AI coding assistants.

Overview

Hooks are callbacks that execute at defined stages of the AI agent loop. They can:

• Observe agent behavior (logging, metrics)
• Block operations (security gates, validation)
• Modify behavior (inject context, transform outputs)

Supported Tools

Installation

go get github.com/agentplexus/assistantkit/hooks

Quick Start

Creating a Hooks Configuration

package main

import (
    "github.com/agentplexus/assistantkit/hooks"
    "github.com/agentplexus/assistantkit/hooks/claude"
)

func main() {
    cfg := hooks.NewConfig()

    // Add a hook before shell commands
    cfg.AddHookWithMatcher(hooks.BeforeCommand, "Bash",
        hooks.NewCommandHook("echo 'Executing command...'"))

    // Add a hook before file writes
    cfg.AddHook(hooks.BeforeFileWrite,
        hooks.NewCommandHook("./scripts/validate-write.sh"))

    // Write to Claude format
    if err := claude.WriteProjectConfig(cfg); err != nil {
        panic(err)
    }
}

Reading an Existing Configuration

package main

import (
    "fmt"
    "github.com/agentplexus/assistantkit/hooks/cursor"
)

func main() {
    cfg, err := cursor.ReadProjectConfig()
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found %d hooks\n", cfg.HookCount())

    for _, event := range cfg.Events() {
        fmt.Printf("Event: %s\n", event)
        for _, hook := range cfg.GetAllHooksForEvent(event) {
            fmt.Printf("  - %s\n", hook.Command)
        }
    }
}

Converting Between Formats

package main

import (
    "os"
    "github.com/agentplexus/assistantkit/hooks"
)

func main() {
    // Read Claude hooks
    data, _ := os.ReadFile(".claude/settings.json")

    // Convert to Cursor format
    cursorData, err := hooks.Convert(data, "claude", "cursor")
    if err != nil {
        panic(err)
    }

    os.WriteFile(".cursor/hooks.json", cursorData, 0644)
}

Event Reference

File Operations

Command Operations

MCP Operations

Session Lifecycle

Tool-Specific Events

Tool Support Matrix

Hook Types

Command Hooks

Execute shell commands when the event fires:

hook := hooks.NewCommandHook("./my-script.sh")
hook = hook.WithTimeout(30)           // 30 second timeout
hook = hook.WithWorkingDir("/tmp")    // Set working directory
hook = hook.WithShowOutput(true)      // Show output (Windsurf)

Prompt Hooks (Claude-only)

Run AI prompts for validation:

hook := hooks.NewPromptHook("Check if this file write is safe")

Configuration Options

cfg := hooks.NewConfig()

// Disable all hooks
cfg.DisableAllHooks = true

// Only allow managed hooks (enterprise)
cfg.AllowManagedHooksOnly = true

// Filter config for specific tool
claudeCfg := cfg.FilterByTool("claude")

Format Examples

Claude Code

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'before bash'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "./validate.sh"
          }
        ]
      }
    ]
  }
}

Cursor

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "echo 'before shell'"
      }
    ],
    "afterFileEdit": [
      {
        "command": "./validate.sh"
      }
    ]
  }
}

Windsurf

{
  "hooks": {
    "pre_run_command": [
      {
        "command": "echo 'before command'",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "./validate.sh"
      }
    ]
  }
}

Architecture

hooks/
├── hooks.go          # Package entry point with re-exports
├── core/
│   ├── event.go      # Canonical event types
│   ├── hook.go       # Hook definition
│   ├── config.go     # Configuration type
│   └── adapter.go    # Adapter interface and registry
├── claude/
│   └── adapter.go    # Claude Code adapter
├── cursor/
│   └── adapter.go    # Cursor IDE adapter
└── windsurf/
    └── adapter.go    # Windsurf adapter

Use Cases

Security Gate

Block dangerous commands:

cfg.AddHookWithMatcher(hooks.BeforeCommand, "Bash",
    hooks.NewCommandHook("./security-check.sh"))

Audit Logging

Log all file modifications:

cfg.AddHook(hooks.AfterFileWrite,
    hooks.NewCommandHook("./audit-log.sh"))

Code Quality

Lint before commits:

cfg.AddHook(hooks.BeforeCommand,
    hooks.NewCommandHook("./pre-commit-check.sh"))

Context Injection

Add context before prompts:

cfg.AddHook(hooks.BeforePrompt,
    hooks.NewCommandHook("./inject-context.sh"))

API Reference

See the Go documentation for complete API reference.

Testing

The hooks package has comprehensive test coverage:

Run tests:

go test ./hooks/...

Run tests with coverage:

go test -cover ./hooks/...

Related

• OmniConfig - Parent project
• OmniConfig MCP - MCP server configuration
• Claude Code Hooks
• Cursor Hooks

License

MIT License - see LICENSE for details.