← Home | Module 05 — Agents & Workflows
0%
Module 05 · Live

Agents & Workflows — Delegate at Scale

An agent is Claude working autonomously toward a goal — reading files, making decisions, writing code, and calling tools — without you watching every step. This module teaches you how to launch agents, wire up hooks, schedule recurring tasks, and coordinate multiple agents working in parallel.

~45 min
🏗 Project: auto-PR agent + hook
🤖 Build while you sleep

🤖 What Are Agents — and How Are They Different?

In every module so far, you've been in a back-and-forth conversation with Claude: you prompt, it responds, you prompt again. An agent breaks that pattern. You give it a goal, it works autonomously until the goal is done.

INTERACTIVE SESSION
  • You prompt → Claude responds → repeat
  • You're present and directing each step
  • Good for creative, exploratory work
  • Ends when you close the session
AGENT
  • You give a goal → Claude executes it fully
  • Reads files, makes decisions, takes actions
  • Good for defined, repeatable tasks
  • Can run in background or on a schedule

The key insight: agents are best for tasks you could write down as a checklist. If you can describe the steps clearly, an agent can execute them — faster, and while you do something else.

Good agent tasks: "Review all open PRs and comment on any missing tests." "Every Monday, read last week's Linear issues and write a summary in Notion." "After every commit, run tests and open a PR if they pass."

⚡ Three Agent Types

Claude Code has three distinct ways to run agentic tasks. Each one fits a different situation.

💬
Type 1

Interactive Agent

You're present, but Claude drives the multi-step work. You give a complex goal and watch it execute — stepping in only if it needs guidance. This is what you've been doing since Module 01.

🌙
Type 2

Background Agent

Runs in the background while you do other things. You launch it, it works, you get a notification when it's done. Uses claude --print or non-interactive mode.

📅
Type 3

Scheduled Agent

Runs automatically on a schedule — daily, weekly, or at a specific time. You set it up once; it runs forever. Powered by cron or the /schedule skill.

🌙 Background Agents — Work While You Work

A background agent is Claude running in non-interactive mode. You fire it off in a terminal, switch to something else, and it completes the task on its own. The --print flag is the key — it tells Claude to run once, print the result, and exit.

Launching a background agent

bash — non-interactive mode
# --print runs Claude non-interactively, outputs result, then exits
claude --print "Review all .js files in src/ for unused variables and write a report to review.md"

# Run it in the background (& sends it to the background)
claude --print "Audit package.json for outdated dependencies and create a report" &

# Pipe output to a file
claude --print "Generate a weekly summary of changes in this repo" > weekly-summary.md

# Run with a specific model for cost control
claude --print --model claude-haiku-4-5 "Format all markdown files in docs/"

Passing context to a background agent

Background agents read your CLAUDE.md automatically, just like interactive sessions. For extra context, use -p to pass a full prompt from a file:

bash
# Write a detailed task file
cat > agent-task.md << 'EOF'
Review the pull request diff below and write a code review.
Focus on: security issues, performance problems, missing tests.
Format: numbered list, one issue per line.
EOF

# Run the agent with the task file as input
claude --print --input-file agent-task.md > code-review.md
Best practice: Give background agents a single, well-scoped goal with a clear output file. Avoid vague tasks like "improve the codebase" — agents work best when "done" is unambiguous.

🪝 Hooks — Automate Reactions to Events

Hooks are shell commands that Claude Code runs automatically when specific events happen — before a tool call, after a tool call, when a session stops, or before context is compressed. They're how you wire Claude into your existing dev workflow.

Think of hooks as triggers: when X happens inside Claude Code, automatically run Y.

Available hook events

HookWhen it firesCommon use
PreToolUseBefore Claude calls any tool (read, edit, bash)Log what Claude is about to do; require approval
PostToolUseAfter each tool call completesAuto-format files; run linter after an edit
StopWhen a session ends or Claude finishes a taskSend a notification; run tests; commit changes
PreCompactBefore /compact runsSave a snapshot of current session state

Configuring hooks in settings.json

Hooks live in your Claude Code settings file. Open it with /config in a session, or edit it directly:

~/.claude/settings.json — hooks config
{
  "hooks": {
    // Run prettier after every file edit
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": "prettier --write $CLAUDE_TOOL_INPUT_PATH" }
        ]
      }
    ],
    // Send a desktop notification when Claude finishes
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

Practical hooks you can use today

Useful hook commands
# Auto-run tests after every file edit
"command": "npm test --silent"

# Auto-lint Python files after edits
"command": "ruff check $CLAUDE_TOOL_INPUT_PATH --fix"

# Git commit automatically when Claude stops
"command": "git add -A && git commit -m 'claude: auto-commit'"

# Mac notification when Claude finishes
"command": "osascript -e 'display notification \"Done\" with title \"Claude Code\"'"

# Windows notification
"command": "powershell -command \"[System.Windows.Forms.MessageBox]::Show('Claude finished')\""

# Linux notification
"command": "notify-send 'Claude Code' 'Task complete'"
Hooks run real shell commands. Test any hook command manually in your terminal first before adding it. A broken hook can silently fail or — if it modifies files — cause unintended changes.

📅 Scheduled Agents — Set It and Forget It

Scheduled agents run automatically at a time you define — once or on a recurring cron schedule. You configure them once and they run without you being present.

Using the /schedule skill

The fastest way to create a scheduled agent is via the /schedule skill inside a Claude session:

Claude prompt — scheduling an agent
# Schedule a one-time task
Use the schedule skill to run this task tomorrow at 9am:
"Read all open Linear issues, write a prioritized daily plan
to daily-plan.md, and create a Notion page from it."

# Schedule a recurring weekly task
Use the schedule skill to run every Monday at 8am:
"Read last week's commits with git log, summarize what changed,
and create a weekly-update.md in the project root."

# Schedule a daily standup prep
Use the schedule skill to run every weekday at 8:30am:
"Read my Linear issues and Notion meeting notes from yesterday,
then write a standup summary to standup.md."

Using cron directly (advanced)

For more control, schedule Claude directly in your system's cron job manager. This runs even when the Claude desktop app is closed:

bash — cron (Mac / Linux)
# Open your crontab file
crontab -e

# Add a line in this format: minute hour day month weekday command
# Run every Monday at 9:00 AM
0 9 * * 1 cd ~/my-project && claude --print "Generate weekly summary" >> weekly.log 2>&1

# Run every day at 8:30 AM (weekdays only)
30 8 * * 1-5 cd ~/my-project && claude --print "Write standup summary to standup.md"
Windows — Task Scheduler
REM Open Task Scheduler → Create Basic Task
REM Set trigger: Daily at 9:00 AM
REM Set action: Start a program
REM Program: cmd.exe
REM Arguments:
/c "cd %USERPROFILE%\my-project && claude --print "Generate weekly summary" >> weekly.log"
Start simple: Schedule one task you currently do manually every week. A "write a weekly summary from git log" agent is a perfect first scheduled task — it's low-risk, high-value, and easy to verify.

🔀 Multi-Agent Patterns

For complex tasks, one agent isn't always enough. Multi-agent systems use an orchestrator — a top-level agent that breaks the work into parts and delegates each part to a specialized subagent.

Orchestrator Agent

🧠 "Audit the entire codebase and write a security report"

🔍
Subagent 1
Scan for SQL injection patterns
🔐
Subagent 2
Check auth & session handling
📦
Subagent 3
Audit npm deps for CVEs

Orchestrator prompt pattern

Claude prompt — orchestrator
You are an orchestrator. Break this task into 3 parallel subtasks
and execute each one completely before combining the results.

Task: Audit this codebase for quality issues.

Subtask 1: Scan all .js files for unused variables and imports.
Subtask 2: Check all API endpoints for missing input validation.
Subtask 3: Review package.json for outdated or vulnerable dependencies.

When all three are done, write a combined report to audit-report.md
with a section for each subtask and a priority-ranked action list.

Parallel vs. sequential agents

Parallel — run simultaneously
  • Independent tasks with no dependencies
  • Faster total completion time
  • Example: lint JS + lint CSS + lint Python
Sequential — run in order
  • Each step depends on the previous output
  • Research → write → review → publish
  • Example: generate code → run tests → fix failures

💡 Power Patterns — Real Workflows to Steal

Pattern 1 — Auto-PR on commit

Wire a Stop hook so every time Claude finishes a coding session, it auto-commits the changes and opens a GitHub PR with a description Claude wrote.

Stop hook + GitHub CLI
# In settings.json Stop hook:
"command": "git add -A && git commit -m \"$(claude --print 'Write a one-line commit message for these staged changes')\" && gh pr create --fill"

Pattern 2 — Nightly code review

Schedule a nightly agent to review the day's commits and post a summary to Slack or save it to Notion.

cron — nightly at 11pm
0 23 * * 1-5 cd ~/my-project && claude --print "Review today's git commits with git log --since=today, identify any risky changes, and write a nightly-review.md"

Pattern 3 — Self-healing tests

Run tests after every edit (PostToolUse hook). If tests fail, Claude automatically reads the failure output and fixes the code.

Interactive session prompt
After every file edit, run npm test. If tests fail, read the
failure output and fix the code. Keep iterating until all
tests pass. Don't ask me for confirmation between iterations.

Pattern 4 — Weekly report agent

Scheduled agent prompt — every Friday at 5pm
Read: git log for this week's commits, open Linear issues,
and any Notion pages updated this week.

Write a weekly-report.md with:
- What shipped (from git log)
- What's in progress (from Linear)
- Blockers (from Linear high-priority issues)
- Next week's focus (top 3 Linear priorities)

Keep it under 300 words. Executive summary tone.
⌨️ Live Terminal Sandbox Interactive
Simulate agent launches and hook events
claude
✓ Claude Code — ready · Module 05 sandbox
Hooks: PostToolUse (prettier) · Stop (notify)
 
Try agent commands below.
 

🎯 Challenge — Wire One Hook and Launch One Background Agent

Two tasks. Both should work on your real project from Module 02.

  1. 1 Add a Stop hook that sends a desktop notification when Claude finishes. Open /config, find the hooks section, and add the notification command for your OS. Test it by running a short Claude task — you should get a notification when it ends.
  2. 2 Launch a background agent with claude --print. Task: "Read all files in this project and write a summary of the codebase to README.md — what each file does in one sentence." While it runs, open a second terminal tab and work on something else. Check README.md when it finishes.
  3. 3 Schedule a recurring task. Use the /schedule skill (or cron) to run a task every weekday morning: "Read the git log from yesterday and write 3 bullet points summarizing what changed to daily-log.md."
  4. 4 Try a self-healing loop. In an interactive session, ask Claude: "Intentionally introduce a syntax error into one of my JS files, then run npm test. Read the failure, fix the error, and run tests again until they pass."

🏗 Mini Project — Auto-PR Agent with Notification Hook

You're going to build a real automation: a background agent that reviews your code, writes a commit message, opens a GitHub PR, and notifies you when it's done — all without you watching. Pick your OS.

Step 1 — Set up a git repo for your project The auto-PR workflow requires git. This step initializes it if you haven't already.

Navigate to your web app project from Module 02 (or any folder with files). Initialize git if it's not already:

macOS / Linux — Terminal # Go to your project from Module 02
cd ~/my-web-app

# Initialize git (skip if already done)
git init
git add .
git commit -m "initial commit"

# Install GitHub CLI if you don't have it
brew install gh
gh auth login
What is the GitHub CLI (gh)? It's a command-line tool that lets you create PRs, issues, and repos from your terminal without opening GitHub in a browser. Claude uses it in the auto-PR step.
Don't want to use GitHub? Skip Steps 4–5 and just run the background review agent without the PR part — it's still a useful automation.
Step 2 — Add a Stop hook for desktop notifications When Claude finishes any task, your computer will notify you — even if you switched to another app.

Open a Claude session in your project, then type /config. This opens your settings.json. Add the Stop hook for your OS:

settings.json — macOS Stop hook // Add inside the "hooks" object:
"Stop": [
  {
    "hooks": [
      { "type": "command", "command": "osascript -e 'display notification \"Task complete\" with title \"Claude Code\"'" }
    ]
  }
]

Save the file. Test it: run any short Claude task and you should get a notification when it ends.

JSON formatting matters. If Claude Code won't start after editing settings.json, the JSON is malformed. Ask Claude: "Validate my settings.json for syntax errors."
Step 3 — Make a small code change to work with The auto-PR agent needs uncommitted changes to review and commit. Let's create some.

Open a Claude session in your project and ask it to make a small improvement:

claude prompt Make a small improvement to this project — add a smooth
fade-in animation to the hero section in styles.css and
trigger it in app.js when the page loads. Keep it subtle.

When Claude finishes, you'll have uncommitted changes in styles.css and app.js. You can verify this with:

bash — check for uncommitted changes git status

You should see both files listed as modified. These are the changes the background agent will review and commit in the next step.

Step 4 — Launch the background review agent Fire the agent and switch away. It runs independently — you'll get notified when it's done.

Open a new terminal window (keep your Claude session open in the original one). In the new window, navigate to your project and run:

macOS — new Terminal window cd ~/my-web-app

claude --print "Review the uncommitted changes with git diff.
Write a clear commit message describing what changed.
Then run: git add -A && git commit with that message.
Finally run: gh pr create --title 'feat: add hero fade animation' --body 'Adds smooth fade-in to hero section on page load'" &

# The & runs it in the background — your terminal is immediately free

Switch to another app and do something else. The agent is working in the background. When it finishes, your Stop hook fires and you get a notification.

What the agent is doing: (1) Reads the git diff, (2) writes a commit message, (3) commits the files, (4) opens a GitHub PR. All without you watching a single step.
Step 5 — Verify the PR and review what the agent did Check that everything worked — the commit, the PR, and the commit message quality.

When you get the notification, check the results:

bash — verify agent output # See the commit the agent made
git log --oneline -3

# List open PRs to confirm it was created
gh pr list

# View the PR in your browser
gh pr view --web

You should see: a commit with a descriptive message Claude wrote, and an open PR on GitHub. Go look at the PR — Claude wrote the title and description from reading the actual diff.

What you just built: A background agent that reviews its own work, writes human-quality commit messages, and opens PRs — completely autonomously. Add this as a Stop hook and every Claude coding session auto-PRs itself.
Step 6 — Save this as a reusable workflow in CLAUDE.md Document the full agent pattern so you can rerun it with one copy-paste.

Open a Claude session in your project and run:

claude prompt Update CLAUDE.md — add an "Agents & Automation" section
that documents the auto-PR background agent we just built.
Include the exact --print command and the Stop hook config.
Also add a note that a desktop notification fires when done.

Claude updates your CLAUDE.md. Next time you want to run this workflow: open Claude, check the Agents section, copy the command, run it. The whole auto-PR process takes 30 seconds to kick off from now on.

Compound value: Every workflow you add to CLAUDE.md makes your next session more powerful. After a month of this, your CLAUDE.md becomes a personal automation library that new team members can immediately use too.