🤖

Agents & Hooks

Spawn autonomous sub-agents that run in parallel, and wire lifecycle hooks to trigger shell commands at every step of the AI's workflow.

Autonomous Parallel Event-Driven Lifecycle

🧠 What It Is

Agents & Hooks are two distinct but complementary powers in Claude Code. Agents let you spawn isolated sub-Claude instances — each with its own context, tools, and task — running in parallel or sequentially. Hooks are shell commands that fire automatically on lifecycle events like tool calls, file writes, or task completion.

Together they let you build complex multi-step AI pipelines: one agent researches, another writes, a third reviews — while hooks validate outputs, format code, and trigger deployments along the way.

Key insight: Agents protect your main context window from bloat. Delegate research, file scanning, or test runs to sub-agents and they return only what matters — keeping the primary conversation focused and fast.

🧭

Orchestrator

Main Claude instance planning the work

🤖

Sub-Agent A

Explore codebase, return findings

🤖

Sub-Agent B

Write tests, return pass/fail

🪝

Hooks

Lint, format, deploy on each step

🪝 Hook Lifecycle Events

Event	When it fires	Common use
PreToolCall	Before Claude calls any tool	Validate permissions, log intent
PostToolCall	After any tool returns	Run linter, format code, check output
PreFileWrite	Before writing a file	Backup, safety check path
PostFileWrite	After a file is written	Run tests, hot-reload dev server
TaskComplete	When Claude finishes a task	Deploy, notify Slack, commit to git
UserPromptSubmit	On every user message	Inject context, validate input

🛠️ 5 Real-World Examples

Example 01

Parallel Code Review

Spawn three agents simultaneously: one checks security vulnerabilities, one reviews performance, one validates tests. Orchestrator merges all findings into a single report.

PromptLaunch three sub-agents in parallel: security-reviewer (scan for OWASP top 10), performance-reviewer (find N+1 queries and slow loops), and test-validator (check coverage gaps). Merge findings into a single markdown report.

Example 02

Auto-Format on Every File Write

Use a PostFileWrite hook to automatically run Prettier on any JS/TS file Claude writes, ensuring consistent formatting without manual intervention.

settings.json hook{"hooks":{"PostFileWrite":[{"matcher":".*\\.(js|ts|tsx)$","command":"npx prettier --write \"${file}\""}]}}

Example 03

Test-Driven Agent Loop

Agent writes a feature, PostFileWrite hook runs tests automatically, hook output is fed back so Claude sees red/green and iterates until all tests pass — no manual test runs needed.

PromptBuild the user authentication module. After each file you write, tests will run automatically. Keep iterating until all tests in auth.test.ts pass.

Example 04

Codebase Explorer Agent

Delegate large codebase exploration to a sub-agent with read-only tools. It scans thousands of files and returns only the relevant 10 — keeping the main context clean.

PromptSpawn an Explore sub-agent to find all API endpoints that accept user input and don't validate it. Report only file paths and line numbers — don't include full file contents.

Example 05

Deploy on Task Completion

Wire a TaskComplete hook to run your deploy script automatically when Claude finishes a task — staging deploy triggered without lifting a finger.

settings.json hook{"hooks":{"TaskComplete":[{"command":"./scripts/deploy-staging.sh && curl -X POST $SLACK_WEBHOOK -d '{\"text\":\"Deploy complete\"}'"}]}}

🤖 Agent & Hook Simulator interactive

Claude Code — Agents & Hooks Sandbox

Type a command or click a quick-action below.

$ _

Pro tip: Keep sub-agent prompts tight and scoped. A sub-agent that returns 3 key facts is 10x more useful than one that dumps 300 lines of file content. Always instruct sub-agents to summarize their output.