Hooks Configuration

Overview

Hooks allow you to execute custom actions when specific events are triggered. Superpowers uses Hooks to automatically inject context at session startup, ensuring the AI assistant knows how to use the skills system.

Supported Events

Event	Trigger	Use Case
SessionStart	Session starts (startup/resume/clear/compact)	Load skill context, show reminders

Configuration File Structure

Hooks are configured in hooks/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

Field Reference

matcher

A regex pattern that matches trigger conditions.

• startup - New session starts
• resume - Session resumed
• clear - After conversation cleared
• compact - After conversation compacted

Example: "startup|resume|clear|compact" triggers on all conditions.

hooks

Array of hook actions, each containing:

Field	Type	Description
type	string	Action type, currently supports command
command	string	Command to execute
async	boolean	Whether to execute asynchronously

async

• false (default): Synchronous execution, blocks session startup until complete
• true: Asynchronous execution, doesn't block session startup

Note: SessionStart hooks should typically be false to ensure context is injected before the session begins.

Built-in Hook Details

session-start

The core Superpowers hook that injects using-superpowers skill content at session startup.

Execution flow:

1. Reads skills/using-superpowers/SKILL.md content
2. Checks for legacy custom skills directory (~/.config/superpowers/skills)
3. Injects content into the system prompt

Output format:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "..."
  }
}

Custom Hook Examples

Example 1: Auto-load Project Config

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.claude/project-context.md 2>/dev/null || echo ''",
            "async": false
          }
        ]
      }
    ]
  }
}

Example 2: Send Notification

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Session started'",
            "async": true
          }
        ]
      }
    ]
  }
}

Configuration File Locations

Platform	Location
Claude Code	~/.claude/plugins/superpowers/hooks/hooks.json
Cursor	~/.cursor/plugins/superpowers/hooks/hooks.json
Codex	~/.codex/superpowers/hooks/hooks.json
OpenCode	~/.config/opencode/superpowers/hooks/hooks.json

Best Practices

Don't Block Session Startup

Avoid long-running operations in SessionStart hooks, or set async: true.

Error Handling

Hook scripts should have robust error handling to prevent session startup failures.

#!/usr/bin/env bash
set -euo pipefail

# Your code...

# Always output valid JSON
echo '{"additionalContext": ""}'

Debugging Tips

1. Manually run the hook script to verify output:

   CLAUDE_PLUGIN_ROOT=~/.claude/plugins/superpowers ./hooks/session-start

2. Check if output JSON is valid:

   ./hooks/session-start | jq .

Platform Compatibility

Superpowers' session-start hook handles different platform output formats:

• Claude Code: Uses hookSpecificOutput.additionalContext
• Cursor and others: Uses additional_context

Disabling Hooks

To temporarily disable Superpowers' auto context injection, modify hooks.json:

{
  "hooks": {
    "SessionStart": []
  }
}