Lesson 5: Scaling Up — Parallel Sessions and Automation

This lesson is advanced and optional. The concepts here are for students who want to push Claude Code further. If you're still getting comfortable with the basics from Lessons 1–4, skip this and come back later. Everything in future modules works without this knowledge.

Fast-track: Already use headless mode, parallel sessions, and the writer/reviewer pattern? You've completed this module. Head to Module 2.

Headless mode: Claude Code in scripts

So far you've used Claude Code interactively — typing prompts, reading responses, approving actions. But Claude Code can also run without a human in the loop.

claude -p "Add JSDoc comments to all exported functions in src/utils/"

The -p flag (for "print") runs Claude Code with a single prompt and exits when done. No interactive session. You'll need to combine it with --allowedTools or --dangerously-skip-permissions to avoid permission prompts for tool use.

This is useful for:

• Running Claude Code as part of a build script
• Batch processing files
• Automating repetitive tasks

claude -p "Review the diff in this PR and add comments about potential issues" --output-format json

for file in src/components/*.tsx; do
  claude -p "Add TypeScript prop types to $file based on how the props are used"
done

Get-ChildItem src/components/*.tsx | ForEach-Object {
  claude -p "Add TypeScript prop types to $($_.FullName) based on how the props are used"
}

Generate documentation:

claude -p "Read the codebase and generate a README.md that explains the project structure, how to install, and how to run it"

Multiple sessions: fresh context for each task

Here's a practical pattern: open multiple terminal windows, each running Claude Code on a different task.

Each session gets its own fresh context. Session A working on the API doesn't pollute Session B working on the UI. This is the context management lesson (Lesson 1) applied at scale.

Some tasks that work well in parallel:

• Writing code in one session, reviewing it in another
• Working on frontend and backend simultaneously
• Fixing bugs in one session while adding features in another

Practical tips for parallel sessions

Running multiple agents sounds simple, but there are real gotchas. Here's what works:

Commit before you branch out. Before starting parallel sessions, commit everything. If one session goes sideways, you can git checkout . to throw away its changes and try again. Without a clean commit point, you're stuck trying to untangle what went wrong.

Assign non-overlapping files. The biggest source of problems: two sessions editing the same file. Assign each session tasks that touch different files — one works on the landing page, another on the dashboard, a third on deployment config. If two sessions change the same file, you'll get merge conflicts.

Use /compact to reset context. Running a long session? Before starting a new task in it, type /compact. This summarizes the conversation and clears old context, so Claude Code isn't confused by stale instructions from a previous task.

3-5 agents is the sweet spot. You can run more, but keeping track of what each one is doing gets hard fast. Start with 2-3 and work your way up as you get comfortable.

The writer/reviewer pattern

This is one of the most effective advanced patterns:

1. Session A (Writer): Build the feature
2. Session B (Reviewer): Review what Session A wrote

The reviewer session has fresh context. It sees the code without all the context of how it was built — just like a human code reviewer would. It catches things the writer session missed because it wasn't biased by the building process.

Fan-out: batch operations

Need to do the same thing across many files? Use headless mode with claude -p in a loop to fan out:

# Add error handling to every API route
for file in src/app/api/*/route.ts; do
  claude -p "Add try/catch error handling to all handlers in $file. Return proper HTTP error responses. Don't change the happy path logic."
done

Each invocation gets a fresh context focused on just one file. This is much more reliable than asking a single session to modify dozens of files.

When running unattended, use --allowedTools to scope what Claude Code can do:

claude -p "Migrate $file from class components to hooks" \
  --allowedTools "Edit,Bash(git commit *)"

This restricts Claude Code to only editing files and committing — it can't run arbitrary commands or delete things. Important safety net for batch operations.

Get-ChildItem src/app/api/*/route.ts | ForEach-Object {
  claude -p "Add try/catch error handling to all handlers in $($_.FullName). Return proper HTTP error responses. Don't change the happy path logic."
}

The --dangerously-skip-permissions flag, revisited

You saw this flag in Module 0, Lesson 4. Here's when it actually makes sense:

• Sandboxed environments (Docker containers, VMs) where damage is contained — ideally without internet access
• Automated pipelines where no human is present to approve and the environment is isolated

claude -p "your prompt" --dangerously-skip-permissions

Use this only in environments where Claude Code can't cause real damage. The flag means exactly what it says — Claude Code will run any command without asking. For most cases, prefer --allowedTools to grant only the specific tools needed:

claude -p "your prompt" --allowedTools "Read,Edit,Bash(npm test)"

GitHub workflows: PRs and code review

If you installed gh (GitHub CLI) in Lesson 4, Claude Code can handle your entire GitHub workflow from the terminal.

Creating pull requests

After building a feature, Claude Code can create the PR for you:

Claude Code reads the diff, writes a title and description, and creates the PR — all without leaving the terminal.

Automated code review

Set up Claude Code as an automated reviewer on your repos. Run claude -p with --output-format json on every new PR:

claude -p "Review the diff in this PR. Flag security issues, missing error handling, and anything that doesn't follow CLAUDE.md conventions. Be specific." --output-format json

You can add this to a GitHub Action so every PR gets an AI review before a human looks at it.

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code review
        run: |
          gh pr diff ${{ github.event.pull_request.number }} | claude -p "Review this diff for bugs, security issues, and missing error handling. Be concise."

Common failure patterns

Before you go, here are the patterns that trip people up. Recognize them early:

Checkpoint

• [ ] I understand headless mode (claude -p) and when to use it
• [ ] I understand the writer/reviewer pattern for catching mistakes
• [ ] I know the common failure patterns and how to avoid them
• [ ] I feel ready to move on to Module 2 (or I know I can come back to this lesson later)

You've completed Module 1. You now know how to work with Claude Code effectively — managing context, giving feedback loops, writing better prompts, setting up your environment, and scaling to parallel sessions.

The difference between a beginner and someone who's productive with Claude Code isn't talent — it's these patterns. Use them.