Welcome to the first unit of Automating Workflows with Hooks! In this course, we'll explore how to transform Claude Code into a powerful development assistant through automation hooks. We'll start by understanding what hooks are and creating your first hook that provides helpful context to Claude when you begin working.

When working with Claude Code, you might find yourself repeatedly providing the same context at the start of each session: explaining your project structure, technology stack, or current development focus. This manual repetition is inefficient and easy to forget. Hooks solve this problem by automating actions at key moments in your workflow.

In this lesson, we'll explore what hooks are, when they trigger, and how to create a simple yet practical hook that automatically provides project context whenever you start a new Claude Code session. By the end, you'll have a working hook that sets the stage for more productive AI-assisted development.

Hooks are like smart automation rules that spring into action at key moments - similar to how your phone automatically backs up photos when you plug it in, or how motion-sensor lights turn on when you walk into a room.

In Claude Code, hooks let you automate repetitive tasks so you don't have to remember them. Instead of telling Claude the same project details every time you start working, a hook can do it automatically. Instead of manually checking if a command is safe before running it, a hook can verify it for you.

The power of hooks lies in their ability to:

• Provide consistent context without you lifting a finger
• Watch for dangerous operations and stop them before they cause damage
• Clean up and organize Claude's work automatically
• Integrate external tools seamlessly into your workflow

Hooks are configured through files in your project's .claude directory, making them version-controlled and shareable across your team - so everyone benefits from the same smart automations.

Claude Code supports several hook events, but we'll focus on the most fundamental one: SessionStart. This event triggers once when a Claude Code session starts or resumes - whether you're beginning a new session, using --resume or --continue, running /resume, clearing with /clear, or after compaction. The event fires right after the environment initializes but before any interaction occurs.

The SessionStart event is particularly useful for:

• Displaying project structure and conventions
• Showing current git branch or deployment status
• Listing available commands or scripts
• Providing technology stack information

Understanding when hooks trigger helps us design automation that feels natural and unobtrusive, enhancing rather than interrupting your workflow.

Let's create a hook script that provides project context when a session starts. We'll place this in the .claude/hooks/ directory:

This script begins with a shebang line (#!/bin/bash) specifying bash as the interpreter, followed by a comment explaining its purpose. The echo commands output structured information about the project, starting with a clear header that makes the context section visually distinct.

The script continues by providing details about the project's architecture:

The directory listing helps Claude understand where different types of code live, while the TECH STACK information provides immediate awareness of the technologies involved. The script ends with exit 0 to signal successful completion.

When this hook executes, Claude receives the following context automatically:

This output appears at the start of your session, immediately orienting Claude to your project's specifics without requiring you to type anything. Everything your script prints to stdout (via echo) becomes part of Claude's context - it's like Claude reading a quick reference card before starting work.

Creating the script is only half the solution; we also need to tell Claude Code when and how to run it. This configuration lives in .claude/settings.json, which controls various aspects of Claude Code's behavior:

This JSON structure defines a mapping between events (like SessionStart) and the actions to take when those events occur.

Let's examine the nested structure more closely. The configuration uses a specific pattern:

• SessionStart: The event type that triggers our hook
• matcher: A filter that determines when the hook runs (empty string means "always")
• hooks array: Contains the actual hook definitions
• type: Specifies command to indicate we're running a shell command
• command: The path to our script relative to the project root

This structure allows for multiple hooks per event and conditional execution based on matchers, providing flexibility for complex workflows.

The matcher field in our configuration is currently an empty string, which means "run this hook for every SessionStart event, regardless of context." We include it explicitly even when empty to show where tool-specific filters would go in other hook types. Matchers provide a way to conditionally execute hooks based on various criteria.

While we're using an empty matcher for simplicity in this first hook, matchers can filter based on:

• Current working directory patterns
• Repository information
• Tool names or commands being executed
• File paths or patterns

This conditional execution becomes powerful when you have different hooks for different project types or development scenarios.

When you start a Claude Code session in a project with this configuration, here's what happens:

1. Claude Code initializes and detects the .claude/settings.json file
2. The SessionStart event triggers
3. The matcher evaluates (always true for empty string)
4. Claude Code executes .claude/hooks/session-start.sh
5. The script's output becomes part of Claude's session context
6. You begin working with Claude already aware of your project details

This automation creates a consistent, repeatable way to provide context, ensuring Claude always starts with the information it needs to assist you effectively.

Before building more hooks, here's how they actually run behind the scenes:

Where hooks run: Hooks execute in Claude Code's current working directory, with $CLAUDE_PROJECT_DIR always pointing reliably to your project root. This means when your hook references .claude/contexts/file.md, use $CLAUDE_PROJECT_DIR/.claude/contexts/file.md to ensure you're looking in the right place.

Two communication channels: Think of hooks as having two speakers:

• stdout (standard output): For SessionStart and UserPromptSubmit hooks specifically, anything written here goes directly to Claude as context. This is the information Claude reads and uses. For other hook types, stdout is only shown in verbose mode.
• stderr (standard error): On a normal exit, stderr may appear in your terminal. On exit code 2 (blocking error), stderr is fed back to Claude as an error message explaining why the action was blocked. Use this for progress updates like "✨ Formatting file..." or warning messages.

Finding your project: The $CLAUDE_PROJECT_DIR environment variable contains your project's full path. It's like having your home address always available - useful for checking if files are where they should be.

Matchers: The matcher field works differently depending on the hook event. For SessionStart, matchers filter on how the session started - use values like "startup" for new sessions, "resume" for resumed sessions, "clear" after /clear, or "compact" after compaction. For tool events like PreToolUse, matchers filter on tool names - use exact tool names like for a single tool, or combine with pipe (the pipe means OR) for multiple tools.

Congratulations! You've learned the fundamentals of hooks in Claude Code: what they are, when they trigger, and how to create a simple SessionStart hook that provides project context. This foundation allows Claude to understand your project automatically, making your development sessions more productive from the very first message.

The hook we created demonstrates a basic but powerful pattern: using automation to eliminate repetitive context-sharing. As you continue through this course, we'll build on these concepts to create more sophisticated hooks that adapt to your workflow, integrate with external tools, and enhance Claude's capabilities in meaningful ways.

Now it's time to practice! In the upcoming exercises, you'll implement this hook yourself and experiment with customizing the context for different project types.