Firing a Shell Command on PostToolUse with Hooks

A PostToolUse hook is a shell command that runs automatically right after a matched tool call finishes.

The most common use is auto-formatting: the moment Claude edits a file, a formatter runs against it without anyone asking.

Summary

Hooks are configured in settings.json, under an event name like PostToolUse.

Each hook entry has a matcher, which limits it to specific tools such as Edit or Write, and one or more hooks commands to run when that matcher fires.

Unlike a slash command, nothing about a hook goes through the model. The harness runs the shell command directly and does not ask Claude whether it should.

A hook receives details about the completed tool call as JSON, typically on stdin, including which file was touched.

Because the hook is deterministic, it is the right place for anything that should happen every single time, with zero exceptions and zero judgment calls.

Recipe

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

When to reach for this:

• Auto-formatting a file the instant it is edited, so formatting never has to be asked for.
• Running a linter and surfacing warnings right after a change, rather than waiting for a separate CI step.
• Logging every file touched during a session for an audit trail.
• Kicking off a fast, narrow test suite for the file that just changed.
• Regenerating a derived artifact (like a compiled config or a type index) after its source changes.

Working Example

#!/usr/bin/env bash
# .claude/hooks/format-on-edit.sh
# Reads the PostToolUse event payload from stdin and formats the touched file.
 
set -euo pipefail
 
payload="$(cat)"
file_path="$(echo "$payload" | jq -r '.tool_input.file_path // empty')"
 
if [ -z "$file_path" ]; then
  exit 0
fi
 
case "$file_path" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
    npx prettier --write "$file_path"
    echo "Formatted: $file_path"
    ;;
  *)
    exit 0
    ;;
esac

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/format-on-edit.sh"
          }
        ]
      }
    ]
  }
}

What this demonstrates:

• The matcher field limits the hook to Edit and Write tool calls, so it never fires on, say, a Bash command.
• The script reads the event payload from stdin and pulls the changed file's path out with jq, rather than guessing at an environment variable.
• A case statement narrows formatting to file types Prettier actually understands, so the hook silently no-ops on files it shouldn't touch.
• The script is a separate, version-controlled file, not an inline one-liner, which makes it testable and readable on its own.
• set -euo pipefail makes the script fail loudly on unexpected errors instead of silently doing nothing.

Deep Dive

How It Works

• Claude Code emits a PostToolUse event immediately after a tool call completes successfully.
• The harness checks every registered PostToolUse hook's matcher against the tool that just ran; only matching hooks execute.
• Each matching hook's command runs as a plain shell command, with the event payload (tool name, tool input, and result) available to it, typically via stdin as JSON.
• The hook's exit code and output are reported back to Claude Code; a non-zero exit is typically surfaced as a failure, useful for hooks that also validate.
• Hooks run synchronously with respect to the tool call finishing, but they do not block or alter the tool call itself, since the tool has already completed by the time PostToolUse fires. That blocking behavior belongs to PreToolUse instead.

Matcher Patterns

Shell Script Notes

# Prefer reading structured input over relying on environment variables
# that may or may not be set consistently across hook implementations.
payload="$(cat)"
file_path="$(echo "$payload" | jq -r '.tool_input.file_path // empty')"
 
# Guard against an empty path before doing any work.
[ -z "$file_path" ] && exit 0

• Always guard against a missing or empty file path; not every tool call payload will have the shape a formatting hook expects.
• Keep the hook fast. It runs on every matching tool call, so a slow hook (a full test suite, a large build) will noticeably slow down every edit.
• Prefer a dedicated script file over a long inline command in settings.json, since it is easier to test, diff, and reason about in isolation.

Gotchas

• Assuming the hook can block or undo the edit - PostToolUse fires after the tool call already completed, so the hook cannot prevent the edit from happening. Fix: use a PreToolUse hook instead if the goal is to reject or block an action before it happens.
• A slow hook makes every edit feel slow - a hook that runs a full test suite or a slow build on every single file edit adds that latency to every edit, not just meaningful ones. Fix: scope the hook to fast operations, or narrow the matcher and file-type check so it only runs where it matters.
• Hardcoding a file path instead of reading it from the event payload - a hook written for one specific file breaks the moment it needs to handle a second file. Fix: always read the actual file path out of the tool call payload, never assume a fixed path.
• Forgetting the matcher and firing on every tool call - an unscoped hook (no matcher, or *) fires even on unrelated tools like Bash or Read, wasting cycles and cluttering output. Fix: set a matcher that names exactly the tools the hook cares about, such as Edit|Write.
• A hook that throws on files it doesn't understand - a formatter invoked against a binary file or an unsupported extension can error out and pollute the session with noise. Fix: add an explicit file-extension guard (like the case statement above) so the hook silently exits on files it isn't meant to touch.
• Treating hook output as invisible - a hook's stdout and exit code are surfaced back into the session, so a chatty or failing hook adds noise (or apparent errors) to every edit. Fix: keep hook output minimal and only non-zero exit on genuine failures the user should see.

Alternatives

FAQs

Related

• Custom Commands, Hooks, and Subagents: What Each One Is For - how PostToolUse fits among the three extension points.
• Blocking Risky File Edits with a PreToolUse Hook - the hook that runs before the edit instead of after.
• Common Hook Events and When to Use Each One - the full catalog of lifecycle events hooks can attach to.
• Custom Commands, Hooks & Subagents Best Practices - conventions for scoping hooks safely.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.