Lesson 36: Headless & CI Mode

Day 36 of 50 · ~7 min read · Phase 5: Advanced Patterns

The Opening Question

So far, every Claude Code interaction you've learned about has been interactive. You type, Claude responds, you read, you decide what to do next.

It's collaborative. It's iterative. It's how most people use Claude Code day-to-day.

But here's a question: what if nobody was watching?

What if Claude Code could run on a server, with no human at the terminal, and make decisions and edits completely automatically? What if you could set it up to review every pull request, run security checks, auto-format code — all while you're asleep?

This is headless mode. No interactive session. No "wait for user input." Just pure automation.

And it raises an interesting question: if Claude can work without watching, should you let it?

Discovery

Question 1: What does "headless" actually mean?

Normally when you use Claude Code:

you: "Review this code"
claude: [generates response]
you: [read it]
you: "Actually, also check the tests"
claude: [generates response]
...

It's interactive. There's a human loop.

Headless mode removes the human loop. It looks like:

trigger: (e.g., new PR opened)
claude: [reads codebase autonomously]
claude: [makes decisions autonomously]
claude: [makes changes autonomously]
claude: [creates commit or comment autonomously]
[no human involved until the result is ready]

When would you want this?

• PR reviews: Automatically review every PR for common issues
• Code formatting: Auto-format code on every commit
• Dependency updates: Test and merge dependency bumps automatically
• Documentation: Auto-generate documentation when code changes

The key insight: these are tasks where you don't need human judgment during the process — you just need to trust the system and review the output.

Question 2: How does Claude Code run in headless mode?

You configure it to run via command line with specific inputs and outputs. For example:

claude --headless --input "src/" --task "review-security"

Or in a GitHub Actions workflow:

- name: Code review with Claude
  run: |
    claude --headless \
      --context "$(git diff origin/main...HEAD)" \
      --task "review-changes"

Key differences from interactive mode:

• No prompts: Claude doesn't ask "should I do this?" — it just does it
• Piped input: You pass context via stdin or files, not conversation
• Structured output: Results go to a file or stdout, not a terminal session
• Error handling: Claude must handle errors gracefully (no "what do you want to do?")

Question 3: What's the --print flag?

The --print flag is how you see what headless Claude would do without actually doing it.

claude --headless --print --task "auto-format code"

This shows you the planned changes:

• Which files it would edit
• What changes it would make
• What commands it would run

It's a safety mechanism. You review the output, and if you like it, you can run without --print.

Why is this important? Because headless mode is powerful but risky. Showing you what it would do before it does it is crucial.

Question 4: When should you trust headless mode, and when should you be careful?

Think about the risk/reward:

Low-risk tasks (safe for fully headless):

• Auto-formatting (tools are deterministic, easy to revert)
• Running tests (read-only, no side effects)
• Generating documentation (easy to review, easy to revert)
• Security scanning (informational, no changes)

High-risk tasks (need human review):

• Making changes to production code (affects users)
• Merging pull requests automatically (changes codebase)
• Deleting files or refactoring broadly (hard to undo)
• Any decision that involves trade-offs (safety vs. performance, etc.)

A good rule of thumb: if you'd do it with a script, you can do it headlessly with Claude. If you'd wait for a human decision, don't run it headless.

The Insight

Headless mode lets Claude Code run without human supervision, which is powerful for repetitive, deterministic tasks. But with that power comes responsibility: you must carefully control what headless Claude is allowed to do, and always use --print to preview changes before they happen.

The mental model: Headless Claude is like setting up automated CI/CD pipelines, but with an AI at the helm. Just as you wouldn't give a script unlimited access to your production database, you shouldn't give headless Claude unlimited access to your codebase. Scope and permissions matter.

Try It

Let's set up a safe headless workflow that reviews code without modifying anything.

1. Create a review script (review.sh):

   #!/bin/bash
   # Review code changes without modifying anything
   
   DIFF=$(git diff origin/main...HEAD)
   
   claude --headless \
     --task "review-changes" \
     --context "$DIFF" \
     --print > review-output.txt
   
   echo "Review complete. See review-output.txt"
   cat review-output.txt
   

2. Make it executable:

   chmod +x review.sh
   

3. Run the review (preview mode):

   ./review.sh
   

4. Read the output: You'll see what Claude Code would do. Since we used --print, no changes were made.

5. If you like the output, run without --print:

   claude --headless --task "review-changes" --context "$(git diff origin/main...HEAD)"
   

Key Concepts Introduced

Bridge to Lesson 37

You've learned to automate consistently (hooks), validate thoroughly (testing), debug holistically (debugging), parallelize work (subagents), and run without supervision (headless).

But there's one more dimension to master: cost.

Claude Code can do amazing things, but every action has a cost. And if you're running it hundreds of times, or on massive codebases, costs add up.

Tomorrow's question: How do you get maximum intelligence per dollar?

← Back to Curriculum · Lesson 37 →