Hook Configuration

:compile - Compilation Checking

Runs mix compile --warnings-as-errors and halts pipeline on failure.

# Check compilation after Claude finishes
stop: [:compile]

# Check compilation after sub-agents finish
subagent_stop: [:compile]

# Check compilation after file edits
post_tool_use: [:compile]  # Auto-filters: :write, :edit, :multi_edit

# Check compilation before git commits
pre_tool_use: [:compile]   # Auto-filters: git commit commands

:format - Format Checking

Runs mix format --check-formatted (checks only, doesn't auto-format).

# Check formatting when Claude finishes
stop: [:format]

# Check formatting after sub-agents
subagent_stop: [:format]

# Check specific file after editing
post_tool_use: [:format]  # Uses {{tool_input.file_path}}

# Check formatting before commits
pre_tool_use: [:format]   # Auto-filters: git commit commands

:unused_deps - Dependency Checking

Runs mix deps.unlock --check-unused to detect unused dependencies.

# Check before git commits only
pre_tool_use: [:unused_deps]

:compile Expansions

:format Expansions

:unused_deps Expansions

Basic Formats

%{
  hooks: %{
    # Simple string format
    stop: ["my_custom_task"],
    
    # Tuple with options
    post_tool_use: [
      {"my_task --args", when: [:write, :edit]}
    ],
    
    # Mix atoms with custom
    stop: [
      :compile,
      :format,
      "my_task"
    ]
  }
}

Hook Options

Tool Matchers (:when option)

# Match single tool
when: :write

# Match multiple tools  
when: [:write, :edit, :multi_edit]

# Match by tool name
when: "Bash"

# Match Bash with command pattern
when: "Bash(git commit:*)"

# For session_start events
when: :startup    # New session only
when: :resume     # Resumed session only
when: :clear      # Clear session
when: "*"         # Any session

# For pre_compact events
when: "manual"    # Manual /compact command
when: "auto"      # Automatic compaction
when: "*"         # Any compaction

# For user_prompt_submit and notification events
when: "*"         # No specific matchers (always match)

Command Patterns (:command option)

# String prefix matching
command: "git commit"

# Regex pattern
command: ~r/^git (commit|push)/

# Only applies when tool is Bash
{"my_task", when: "Bash", command: ~r/^npm/}

Pipeline Control

# Stop all subsequent hooks if this fails
{"compile", halt_pipeline?: true}

# Continue even if this fails  
{"optional_check", halt_pipeline?: false}

# Non-blocking (informational only)
{"credo --strict", blocking?: false}

pre_tool_use

Runs before tool execution (can block the tool).

pre_tool_use: [
  {"validate_command", when: "Bash"},
  {:compile, when: "Bash", command: ~r/^git commit/}
]

post_tool_use

Runs after tool execution (file edits, etc).

post_tool_use: [
  {:compile, when: [:write, :edit]},
  {:format, when: [:write, :edit]}
]

user_prompt_submit

Runs before processing user prompts (can add context or block).

user_prompt_submit: [
  {"validate_prompt", blocking?: true},
  {"add_context", blocking?: false}
]

notification

Runs when Claude needs permission or input is idle.

notification: [
  {"send_desktop_notification", blocking?: false}
]

stop

Runs when Claude Code finishes responding.

stop: [:compile, :format, "my_final_check"]

subagent_stop

Runs when a sub-agent task completes.

subagent_stop: [:compile, :format]

pre_compact

Runs before context compaction (manual or automatic).

pre_compact: [
  {"save_state", when: "manual"},
  {"cleanup_context", when: "auto"}
]

session_start

Runs when Claude Code starts a new session.

session_start: [
  {"load_env", when: :startup},
  {"restore_state", when: :resume}
]

Pre-Commit Validation

%{
  hooks: %{
    pre_tool_use: [
      # All checks before git commits
      :compile,
      :format,
      :unused_deps
    ]
  }
}

Immediate Feedback on Edits

%{
  hooks: %{
    post_tool_use: [
      # Fast feedback after editing
      :compile,
      :format
    ]
  }
}

CI-Style Pipeline

%{
  hooks: %{
    stop: [
      # Run all checks, stop on first failure
      {"compile --warnings-as-errors", halt_pipeline?: true},
      {"format --check-formatted", halt_pipeline?: true},
      {"test", halt_pipeline?: true},
      {"credo --strict", halt_pipeline?: true},
      {"dialyzer", halt_pipeline?: true}
    ]
  }
}

Custom Linting

%{
  hooks: %{
    post_tool_use: [
      :format,
      {"credo suggest", when: [:write, :edit], blocking?: false}
    ],
    stop: [
      {"credo --strict", halt_pipeline?: true}
    ]
  }
}

Environment-Specific Hooks

%{
  hooks: %{
    stop: [
      {"test", env: %{"MIX_ENV" => "test"}},
      {"compile", env: %{"MIX_ENV" => "prod"}}
    ]
  }
}

Shell Commands vs Mix Tasks

%{
  hooks: %{
    # Mix tasks (default - no prefix needed)
    stop: [
      "compile",                    # Runs: mix compile
      "test --cover"                # Runs: mix test --cover
    ],
    
    # Shell commands (use "cmd " prefix)
    post_tool_use: [
      {"cmd echo 'File edited'", blocking?: false},
      {"cmd ./scripts/lint.sh", env: %{"MODE" => "strict"}}
    ]
  }
}

Phoenix Project

%{
  hooks: %{
    stop: [:compile, :format],
    post_tool_use: [
      :compile,
      :format,
      {"phx.routes", when: [:write], blocking?: false}
    ],
    pre_tool_use: [:compile, :format, :unused_deps]
  }
}

Library Development

%{
  hooks: %{
    stop: [
      :compile,
      :format,
      "test",
      "docs"
    ],
    post_tool_use: [:compile, :format],
    pre_tool_use: [
      :compile,
      :format,
      {"ex_doc --version", halt_pipeline?: true}
    ]
  }
}

Strict Quality Checks

%{
  hooks: %{
    stop: [
      {"compile --all-warnings", halt_pipeline?: true},
      {"format --check-formatted", halt_pipeline?: true},
      {"test --cover", halt_pipeline?: true},
      {"credo --strict", halt_pipeline?: true},
      {"dialyzer", halt_pipeline?: true},
      {"doctor", halt_pipeline?: true}
    ]
  }
}