Custom Hooks

Hooks are shell commands that run automatically in response to events during your ACT session. They let you automate repetitive tasks without modifying the core workflow.

How hooks work

Claude Code supports hooks that trigger at specific points in its lifecycle. ACT Pro includes pre-configured hooks and lets you add your own.

Hooks are defined in your Claude Code settings file (.claude/settings.json or the project-level equivalent). Each hook specifies:

• An event --- when to run (before/after a tool call, on notification, etc.)
• A matcher (optional) --- which tool or pattern triggers it
• A command --- the shell command to execute

Included hooks

ACT Pro ships with these hooks enabled by default:

Session logging

Logs session start and end events to a local file. Useful for tracking time spent on AI-assisted work.

Dart auto-format

Runs dart format on Dart files after they are written or modified. This keeps your code formatted consistently without manual intervention.

Statusline

Updates a terminal statusline with the current ACT workflow stage. Gives you visibility into what the AI is doing without scrolling through the conversation.

Adding custom hooks

Custom hooks are defined in the hooks section of your Claude Code settings. Here is the general structure:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "optional pattern",
        "command": "shell command to run"
      }
    ]
  }
}

Example: run tests after file changes

This hook runs flutter test after any Dart file is written:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write_file:*.dart",
        "command": "flutter test --reporter compact 2>/dev/null || true"
      }
    ]
  }
}

Example: notify on task completion

This hook sends a system notification when ACT finishes a workflow command:

{
  "hooks": {
    "Notification": [
      {
        "command": "osascript -e 'display notification \"$CLAUDE_NOTIFICATION\" with title \"ACT\"'"
      }
    ]
  }
}

Available events

Event	When it fires
PreToolUse	Before a tool call is executed
PostToolUse	After a tool call completes
Notification	When Claude Code sends a notification (e.g., task complete, waiting for input)
Stop	When the assistant stops responding

Tips for custom hooks

• Keep hooks fast. Slow hooks block the workflow. If a hook takes more than a few seconds, run it asynchronously (append & to the command).
• Handle failures gracefully. Append || true to commands that might fail, so a hook failure does not interrupt the workflow.
• Use matchers to scope hooks narrowly. A hook that runs on every tool call adds overhead. Use matchers to target specific tools or file patterns.
• Test hooks outside ACT first. Run the shell command manually to verify it works before adding it as a hook.

Claude Code hooks documentation

For the full hooks specification, including all available events, environment variables, and matcher syntax, see the Claude Code hooks documentation.

Related

• Starter vs Pro --- hooks require ACT Pro
• Workflow Overview --- understand the pipeline hooks integrate with