# Hooks: Run Code When Claude Code Acts

Control what Claude Code can and cannot do by running your own scripts
before and after every tool call. Hooks are the mechanism behind security
guardrails, audit trails, and AI-powered approval workflows.

Companion repo for the article
[Hooks: Run Code When Claude Code Acts](https://fromaitochitta.com/cc-024) on From AI to Chitta.

---

## What You Will Learn

By working through the exercises in this repo, you will be able to:

- Block dangerous commands with pre-tool-use hooks before they ever execute
- Build automatic audit trails with post-tool-use hooks that log every action
- Create prompt-based hooks where Claude evaluates a decision before proceeding

These are not theoretical outcomes. Complete the exercises and you will
have working hooks you can configure in any Claude Code project.

## Prerequisites

- Claude Code installed and running (`claude --version` prints a version)
- Basic shell scripting knowledge (read a bash script, understand exit codes)
- Python 3 (for JSON parsing in the hook scripts; comes with macOS)

No npm install, no Docker, no build step.

## Exercises

| # | Exercise | What It Covers |
|---|----------|---------------|
| 01 | [Block Dangerous Commands](exercises/01-block-danger.md) | PreToolUse hooks, exit codes, blocking behavior |
| 02 | [Build an Audit Trail](exercises/02-audit-trail.md) | PostToolUse hooks, append-only logging |
| 03 | [Prompt-Based Approval](exercises/03-prompt-hooks.md) | AI-powered hooks, risk evaluation before acting |

Start at `exercises/01-block-danger.md`. Each exercise links to the next.

## How to Use This Repo

**"Show me what it does":** Read through `hooks/pre-tool-use.sh` and
`hooks/post-tool-use.sh`. Then read `.claude/settings.json` to see how
they are wired in. The pattern becomes clear before you run anything.

**"Let me actually do it":** Open Claude Code in this directory and
follow the exercises in order. Each one has an expected output section
so you know when you have succeeded.

```bash
git clone https://git.fromaitochitta.com/fromaitochitta/claude-code-hooks.git
cd claude-code-hooks
claude
```

Then open `exercises/01-block-danger.md` and follow the steps.

## Domain

**Claude Code Automation** - This repo is part of the Claude Code Automation series on
From AI to Chitta. See the full series for related concepts.

## About

Built by [Kjell Tore Guttormsen](https://fromaitochitta.com) as
part of the From AI to Chitta project, exploring the intersection
of AI tools and inner development.

MIT License.