Claude Code hooks for Elixir and Phoenix

Hooks

The plugin ships 23 hooks across 10 lifecycle events. They are the deterministic layer: skills and agents are instructions a model may or may not follow, hooks are shell scripts that always run.

That distinction is the whole reason they exist. Session analysis across 400 sessions measured CLAUDE.md prose rules firing ~0% of the time — the rules were correct and simply never consulted. Anything that genuinely must happen lives here instead.

Every script is plain, auditable bash in plugins/elixir-phoenix/hooks/scripts/. No telemetry, no network calls except a localhost Tidewave probe and git fetch.

Contents

• The five things hooks do
• What fires when
• Full hook list
• Two rules that govern all of them
• Turning hooks off
• Deep dives

The five things hooks do

1. Stop destructive commands. mix ecto.reset, mix ecto.drop, MIX_ENV=prod mix …, and force pushes are denied before they execute, with a safer alternative attached so Claude does not just retry.

2. Verify code against the Iron Laws. After every edit to an Elixir file, the content you just wrote is scanned for seven of the non-negotiable rules — :float for money, String.to_atom on user input, raw/1 with a variable, implicit cross joins, unsupervised start_link, and more. A violation feeds the specific law and line back to Claude for correction.

3. Get context to models that cannot read it themselves. Subagents start with fresh context and cannot reliably read plugin reference files. A SubagentStart hook injects all 26 Iron Laws into every one. A UserPromptSubmit hook spots PR URLs and stack traces and suggests the right /phx: command.

4. Keep the plan workflow coherent. Writing a plan.md hard-stops the run so you can review before implementation. Compaction re-injects the current phase’s rules and your scratchpad’s dead ends. An API failure leaves a breadcrumb the next session reads.

5. Break debugging loops. Repeated mix failures escalate from generic hints to a structured critic that consolidates the error history and tells Claude to stop retrying — the Critic→Refiner pattern from AutoHarness (Lou et al., 2026).

What fires when

  session opens
      │
      ├─ SessionStart ······ setup dirs · detect Tidewave · detect Ash
      │                      resume banner · scratchpad · branch freshness
      ▼
  you type a prompt
      │
      ├─ UserPromptSubmit ·· PR URL / stack trace → suggest a /phx: command
      ▼
  Claude picks a tool
      │
      ├─ PreToolUse ········ BLOCK destructive bash · deps gate · edit freeze
      ▼
    tool runs ──────────────────┐
      │                         │ (failed)
      │ (ok)                    ▼
      │                    PostToolUseFailure ·· mix hints → loop critic
      ▼
      ├─ PostToolUse ······· format · Iron Laws · debug stmts · security
      │                      plan STOP · edit metrics
      │
      ├─ SubagentStart ····· inject Iron Laws into every spawned agent
      ▼
  context fills up
      │
      ├─ PreCompact ········ re-inject phase rules + scratchpad dead ends
      ├─ PostCompact ······· verify plan state survived
      ▼
  turn ends
      │
      ├─ Stop ·············· warn about background tasks / crons
      └─ StopFailure ······· log API failure for next session's resume

Full hook list

PreToolUse — can block

PostToolUse — advises after the edit

PostToolUseFailure — when mix fails

UserPromptSubmit / SubagentStart — context injection

SessionStart

Compaction and exit

Two rules that govern all of them

Everything Elixir-specific is gated on mix.exs

Every hook checks for mix.exs before doing anything. Open a Rust or Python repo with the plugin installed globally and it is inert — no directories created, no Phoenix Iron Laws injected, no banners.

The single deliberate exception is the force-push block, which is dangerous in any repository and stays global.

This gating (added in v2.10.1, issue #55) is what makes it safe to enable the plugin globally rather than per-project.

Hooks fail open, never closed

No hook uses set -e. Denials are expressed as JSON data, never as an exit code, and the always-on Bash gate is registered as script.sh || exit 0.

This is not theoretical. The safety script once got corrupted by merge-conflict markers, and because bash exited non-zero, every Bash command in the session was blocked. A broken hook must degrade to “the guard is off”, never to “the session is unusable”.

Turning hooks off

The plugin does not ship a global switch, and most hooks are advisory — they print a message and get out of the way. For the ones that block:

To disable a hook outright, remove its entry from plugins/elixir-phoenix/hooks/hooks.json in your installed copy, or uninstall the plugin. /reload-plugins picks up the change without a restart.

Deep dives

Each group has a reference page with the patterns, the failure modes they were built from, and the exact output you see:

Contributors adding or changing a hook should start with the contributor guide, which carries the per-event output-channel table and the shared conventions.