Hook API

Claude Code Hook system and the hooks used by the Notifier plugin.

Claude Code Hooks Overview

Claude Code can run user-defined scripts on specific events.

Available Hooks

Hook	Trigger	Use Case
UserPromptSubmit	User submits prompt	Time tracking, logging
Stop	Claude response complete	Task completion notification
Notification	Permission request, idle state	Immediate notification
SessionEnd	Session ends	Cleanup

hooks.json Structure

{
  "hooks": {
    "HookName": [
      {
        "matcher": "optional_matcher",
        "hooks": [
          {
            "type": "command",
            "command": "script path"
          }
        ]
      }
    ]
  }
}

Fields

Field	Required	Description
matcher	No	Event filter (used in Notification Hook)
type	Yes	Always "command"
command	Yes	Script path to execute

Hooks Used by Notifier

UserPromptSubmit

Saves timestamp on user input.

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/save-prompt.sh"
      }]
    }]
  }
}

save-prompt.sh behavior:

# Save current time to file
date +%s > "$DATA_DIR/timestamp-${SESSION_ID}.txt"

Stop

Sends notification when Claude response completes.

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
      }]
    }]
  }
}

notify.sh behavior:

1. Compare saved timestamp with current time
2. Send notification if over minimum duration (default 20s)

Notification

Sends immediate notification on permission request or idle state.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      }
    ]
  }
}

matcher values:

matcher	Description
permission_prompt	File creation, command execution permission
idle_prompt	Waiting for user input

SessionEnd

Cleans up temp files on session end.

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/cleanup-session.sh"
      }]
    }]
  }
}

Environment Variables

Available in hook scripts:

Variable	Description
CLAUDE_PLUGIN_ROOT	Plugin root path
SESSION_ID	Current session ID
NOTIFICATION_TYPE	Notification type (Notification Hook)

Full hooks.json Example

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/save-prompt.sh"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
      }]
    }],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      }
    ],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/cleanup-session.sh"
      }]
    }]
  }
}