DEV Community

Shrijith Venkatramana
Shrijith Venkatramana

Posted on

Claude Code Hooks 101: Turning Your AI Coding Assistant Into an Automated Teammate

#ai #productivity #programming #webdev

Hello, I'm Shrijith Venkatramana. I'm building git-lrc, an AI code reviewer that runs on every commit. Star Us to help devs discover the project. Do give it a try and share your feedback for improving the product.

Most developers use Claude Code like a very smart terminal assistant.

Very few realize it has an event system.

And that changes the possibilities for extension in a big way.

Hooks let you intercept what Claude is doing while it’s doing it. Before a command runs. After a file changes. When a prompt is submitted. When a session starts. Even when an MCP tool gets called.

Which means Claude Code is not just “AI in terminal”.

It becomes programmable infrastructure.

You can:

  • block dangerous commands
  • auto-run linters
  • inject project context dynamically
  • validate deployments
  • wire Claude into internal tooling
  • create approval systems
  • build autonomous workflows around the agent loop itself

The official hooks reference is dense and comprehensive . This guide is the practical “Hooks 101” version I wish I had when first exploring it.

1. What Hooks Actually Are

Claude Code hooks are event-driven automations.

A hook runs when something specific happens inside Claude Code.

Examples:

Event When it fires
SessionStart Claude session begins
UserPromptSubmit Before Claude sees your prompt
PreToolUse Before a tool runs
PostToolUse After a tool succeeds
Stop When Claude finishes responding

The official lifecycle diagram is massive because hooks cover almost the entire Claude execution lifecycle .

Conceptually though, it’s simple:

Event happens
    ↓
Hook receives JSON context
    ↓
Your code decides what to do
Enter fullscreen mode Exit fullscreen mode

That’s it.

The hook can:

  • observe
  • block
  • modify
  • enrich context
  • trigger external systems
  • notify humans
  • persist state

Think of it like middleware for AI behavior.

2. The Core Mental Model

A hook configuration has 3 layers:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./check.sh"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

This maps to:

Event
  ↓
Matcher
  ↓
Handler
Enter fullscreen mode Exit fullscreen mode

Event

“What lifecycle point do I care about?”

Example:

  • PreToolUse
  • SessionStart
  • PostToolUse

Matcher

“What specifically should trigger this?”

Example:

"matcher": "Bash"
Enter fullscreen mode Exit fullscreen mode

or

"matcher": "Edit|Write"
Enter fullscreen mode Exit fullscreen mode

or regex:

"matcher": "^Notebook"
Enter fullscreen mode Exit fullscreen mode

Handler

“What should run?”

Example:

  • shell command
  • HTTP endpoint
  • MCP tool
  • prompt evaluation
  • subagent

That architecture is surprisingly elegant.

It avoids the usual “AI plugin spaghetti”.

3. Your First Useful Hook

Here’s the classic example from the docs: block destructive shell commands.

Configuration 

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "./block-rm.sh"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Script 

#!/bin/bash

COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked"
    }
  }'
else
  exit 0
fi
Enter fullscreen mode Exit fullscreen mode

Now Claude literally cannot execute rm -rf.

That’s important.

Most people think AI safety means “better prompting”.

Hooks are stronger than prompting because they operate at execution boundaries.

This is policy enforcement.

Not suggestion.

4. The Most Underrated Feature: Context Injection

This is where hooks become extremely powerful.

Hooks can dynamically inject context into Claude’s reasoning loop.

The docs call this additionalContext.

Example:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit schema.ts instead."
  }
}
Enter fullscreen mode Exit fullscreen mode

That means Claude learns contextual rules at runtime.

This is vastly more scalable than stuffing everything into CLAUDE.md.

You can inject:

  • current git branch
  • deployment target
  • CI status
  • active incidents
  • ownership rules
  • generated-file warnings
  • monorepo-specific conventions

And because hooks run conditionally, context becomes adaptive instead of static.

This is the missing piece in many “AI engineering” setups.

People obsess over giant system prompts.

But dynamic context systems are usually more important.

5. Hooks Are Basically an Internal Event Bus

Once this clicks, your architecture changes.

Claude Code emits events.

Hooks consume them.

That means you can build automation around the AI agent loop itself.

Some genuinely interesting patterns:

Auto-lint after edits 

{
  "matcher": "Edit|Write"
}
Enter fullscreen mode Exit fullscreen mode

Run:

  • ESLint
  • Ruff
  • cargo fmt
  • gofmt
  • typecheck

immediately after Claude edits files.

Security review for Bash commands

Intercept shell execution:

{
  "matcher": "Bash"
}
Enter fullscreen mode Exit fullscreen mode

Then:

  • deny production DB access
  • block credential exposure
  • detect curl | sh
  • prevent unsafe Docker commands

AI deployment approvals

Before deploy scripts execute:

{
  "if": "Bash(kubectl apply *)"
}
Enter fullscreen mode Exit fullscreen mode

Require:

  • ticket number
  • staging validation
  • human approval
  • CI success

This is much closer to real enterprise governance than “just trust the AI”.

MCP-aware workflows

Claude hooks can even intercept MCP tool calls using patterns like:

"matcher": "mcp__github__.*"
Enter fullscreen mode Exit fullscreen mode

or

"matcher": "mcp__memory__.*"
Enter fullscreen mode Exit fullscreen mode

That opens interesting possibilities:

  • audit MCP usage
  • rate limit expensive tools
  • add policy layers
  • validate writes
  • enrich tool outputs

Most people haven’t realized yet that MCP tools effectively become part of Claude’s operating system.

Hooks let you instrument that OS.

6. The Five Types of Hooks

The docs define five handler types.

Each unlocks a different architecture style.

1. Command Hooks

Run shell scripts.

Most common.

{
  "type": "command"
}
Enter fullscreen mode Exit fullscreen mode

Good for:

  • scripts
  • validation
  • git integration
  • local automation

2. HTTP Hooks

Send events to web services.

{
  "type": "http"
}
Enter fullscreen mode Exit fullscreen mode

Good for:

  • centralized policy engines
  • telemetry
  • dashboards
  • org-wide governance

This is where enterprise adoption gets serious.

3. MCP Tool Hooks

Call MCP tools directly.

{
  "type": "mcp_tool"
}
Enter fullscreen mode Exit fullscreen mode

Good for:

  • internal platforms
  • security tooling
  • knowledge systems
  • automation frameworks

4. Prompt Hooks

Use another Claude call to evaluate behavior.

{
  "type": "prompt"
}
Enter fullscreen mode Exit fullscreen mode

Example:

Determine whether this command appears dangerous.
Return allow or deny.
Enter fullscreen mode Exit fullscreen mode

This creates AI supervising AI.

5. Agent Hooks

Spawn subagents that can investigate before deciding.

This is the wildest category.

You can have an agent:

  • inspect repo state
  • search for policy violations
  • analyze diffs
  • verify architecture constraints

before allowing another agent to proceed.

We’re entering “agents supervising agents” territory now.

7. What Makes Hooks Different From Traditional Dev Automation

Hooks are not just glorified Git hooks.

The difference is placement inside the agent loop.

Traditional automation usually happens:

Developer → Tool → CI
Enter fullscreen mode Exit fullscreen mode

Hooks happen during reasoning and execution:

Developer
   ↓
Claude reasoning
   ↓
Hook interception
   ↓
Tool execution
   ↓
Hook feedback
   ↓
Claude adapts
Enter fullscreen mode Exit fullscreen mode

That feedback loop matters.

Claude can react to hook output.

A hook is not merely rejecting an action.

It’s shaping the agent’s future behavior during the session.

That’s a fundamentally different model from static automation pipelines.

Final Thoughts

Claude Code hooks quietly transform Claude from:

“AI assistant that can run commands”

into:

“programmable AI runtime with policy, orchestration, and adaptive context.”

That’s a much bigger idea.

Especially once MCP ecosystems mature.

I suspect many future “AI engineering platforms” will essentially be:

  • models
  • tools
  • event systems
  • policy layers
  • context injection systems

…and hooks are one of the first serious implementations of that architecture developers can actually touch today.

The full hooks reference is worth reading once you understand the mental model behind it.

So now I’m curious:

What’s the first hook you’d build?

*AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.*

Any feedback or contributors are welcome! It's online, source-available, and ready for anyone to use.

GitHub logo HexmosTech / git-lrc

Free, Micro AI Code Reviews That Run on Commit



AI agents write code fast. They also silently remove logic, change behavior, and introduce bugs -- without telling you. You often find out in production.

git-lrc fixes this. It hooks into git commit and reviews every diff before it lands. 60-second setup. Completely free.

See It In Action

See git-lrc catch serious security issues such as leaked credentials, expensive cloud operations, and sensitive material in log statements

git-lrc-intro-60s.mp4

Why

  • 🤖 AI agents silently break things. Code removed. Logic changed. Edge cases gone. You won't notice until production.
  • 🔍 Catch it before it ships. AI-powered inline comments show you exactly what changed and what looks wrong.
  • 🔁 Build a…
View on GitHub

Top comments (0)