Automation and Scale: Headless -p Into CI, Parallel Sessions and Worktrees, Writer/Reviewer Dual Sessions, Adversarial Review, Common Failure Modes; a 20-Line Minimal Agent SDK Agent

Today's Goals

1. Run an unattended task with claude -p, and parse the --output-format json result to judge success or failure
2. Run multiple parallel sessions with worktrees, and design a Writer/Reviewer dual-session adversarial review
3. Write a 20-line minimal agent with the Agent SDK, and name the fix for five common failure modes

For four days you have been sitting beside the teammate. Today you leave the chair: it works with nobody watching, several of them work at once, and they check each other's work. Once you have read this and finished the lab, scroll back up and tick off the three goals — and the course is done.

Plain-Language Walkthrough

Headless mode: claude -p turns the teammate into one command

A capable teammate eventually meets a request like this: "for every incoming PR, do a pass for spelling mistakes," or "every night, group today's error logs by cause." That work needs no conversation at your side, only a command a script can call.

claude -p "your prompt" is that command — headless mode (-p is short for print). It never enters the interactive interface: it runs the prompt, writes the result to standard output, and exits, with exit code 0 for success and non-zero for failure, so a shell script can branch on it directly. It also takes a pipe like any Unix tool:

# a one-off question
claude -p "What does this project do?"
 
# pipe data in: feed it the build log, write the explanation to a file
cat build-error.txt | claude -p "Briefly explain the root cause of this build error" > explain.txt
 
# use it as a typo linter: it only sees the diff and needs no Bash permission
git diff main | claude -p "You are a spell checker. Report every spelling mistake in the diff, one per line as file:line, and output nothing else."

The third one deserves a second look: piping the diff in means Claude needs no tool permissions at all and answers purely from its input — the safest possible shape for an unattended job. Running in CI also wants --bare: it skips auto-discovery of hooks, skills, plugins, MCP, and CLAUDE.md, so results are identical on every machine and startup is faster, and it sidesteps the hazard at the end of D4 — somebody else's hooks from an unfamiliar repository executing on your CI runner. The documentation says plainly that --bare will become the default for -p in the future. Note that --bare does not read your subscription login, so ANTHROPIC_API_KEY must be set.

Parsing the JSON result: result, session_id, cost, and turns

A script judging whether something succeeded and what it cost needs more than a block of prose. Add --output-format json and the output becomes a JSON object with several key fields:

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Found 3 spelling mistakes: …",
  "session_id": "3f9c…",
  "num_turns": 4,
  "duration_ms": 18234,
  "total_cost_usd": 0.0421,
  "usage": { "input_tokens": 12034, "output_tokens": 812, "cache_read_input_tokens": 9800 }
}

result is the final answer; is_error and subtype tell you success or failure; num_turns is how many think-call-tool-read-result rounds it took; total_cost_usd is the estimated cost of this run (a client-side estimate that may differ from the bill, but good enough for budget control); and session_id lets you continue with --resume. There is a further step too: pass a JSON Schema with --json-schema and the result gains a structured_output field that strictly matches your schema — the structured output from D1, reappearing at the CLI layer.

When you need to handle events one at a time, use --output-format stream-json --verbose: one JSON event per line, with system/init first (carrying the model, the tools, and the status of loaded plugins and MCP servers — CI can use it to check that everything meant to load actually loaded) and a result of the same shape as above last. In a script, jq -r '.result' takes the text and jq '.total_cost_usd' the cost, or you write a 20-line TS / Python wrapper as in today's lab: call claude -p, parse the JSON, and exit non-zero on an error or a budget overrun.

Three locks before CI: permissions, budget, reproducibility

Before leaving the teammate alone in the office overnight, you lock three doors.

Lock one: permissions. Unattended, nobody is there to answer "allow?", so either state up front what is allowed or refuse everything that would ask. --allowedTools allowlists specific tools: "Read,Grep" is a read-only review; "Bash(git diff *),Bash(git log *)" allows only a couple of git commands — and mind the space before *, since git diff* without it would also admit git diff-index. --permission-mode sets the baseline: dontAsk is the strictest CI mode, refusing anything off the allowlist; acceptEdits permits file edits while commands stay restricted; auto lets the classifier model review on your behalf. The starting mode for -p is Manual on every plan, so you must pass it explicitly. Pair it with --permission-prompts none so anything that would have asked a human is refused outright, with the model told not to retry.

Lock two: budget. --max-turns N caps turns and --max-budget-usd 0.50 caps spend, stopping with an error when either is reached. Without those two, one task stuck in a loop can burn a month's quota.

Lock three: reproducibility. --bare turns off auto-discovery of local configuration; --no-session-persistence keeps nothing on disk; and the model, the prompt, and any system prompt appendix (--append-system-prompt) all live in the script under version control. Put together, the command looks like this:

gh pr diff "$PR" | claude --bare -p \
  --append-system-prompt "You are a security reviewer. Report vulnerabilities and risks only; do not comment on style." \
  --permission-mode dontAsk --permission-prompts none \
  --max-turns 6 --max-budget-usd 0.50 \
  --output-format json > review.json
 
jq -r '.result' review.json | gh pr comment "$PR" --body-file -

Parallel sessions and worktrees: several jobs at once without stepping on each other

One teammate is no longer enough and you want three at once: one fixing a bug, one writing a feature, one tidying docs. The problem is that three of them editing files in the same directory will overwrite each other.

Git worktrees solve this: one repository, several independent working directories, each on its own branch. Claude Code turns it into a flag: claude --worktree feature-auth (or -w) creates a worktree under .claude/worktrees/feature-auth/, checks out the worktree-feature-auth branch, and starts a session inside it. Open another terminal, run claude --worktree fix-login, and the two sessions work in directories that cannot disturb each other. When a session ends it checks that worktree for uncommitted changes: clean means it is removed automatically, and if there is work in progress it asks whether to keep or delete it.

Two practical details: add .claude/worktrees/ to .gitignore; and a worktree is a fresh checkout, so gitignored files such as .env do not come along — put a .worktreeinclude file in the project root listing the file names to copy. Subagents can use worktrees for isolation too: write isolation: worktree in the frontmatter of .claude/agents/<name>.md and that subagent always edits files inside its own temporary worktree.

The other shape of parallelism is not several different jobs but the same job done by several parties who then read each other's work — which is the next section.

Writer / Reviewer and adversarial review: let another context find the flaws

Having the person who wrote the code review their own code usually works poorly — not out of bad faith, but because their head is still full of every reason they wrote it that way, which is hard to step outside of. The same is true for Claude: a session that just finished an implementation has its whole chain of reasoning in context, and asked to review itself it tends to confirm rather than question.

The fix is to review from a context that has none of those memories. The simplest shape is two terminals:

Session B reads the code from scratch and sees only the diff and the standard you gave it, with no idea why A wrote it that way — so what it finds are flaws in the code itself. The same idea works for tests: one session writes the tests, another writes the implementation that has to pass them.

If you would rather not run two terminals, use the subagent from D4 for an adversarial review: "use a subagent to review this diff against PLAN.md: is each requirement implemented, does every listed edge case have a test, and does anything go beyond the task's scope. Report gaps only; do not comment on style." A subagent's separate context is that reviewer without memories by construction. Claude Code also ships /code-review, which reviews the current diff for bugs in a fresh subagent.

One side effect you must know about: ask a reviewer to find problems and it will definitely find problems — even flawless code gets a few reported, because that is the job it was given. Accepting all of it uncritically leads to over-engineering: superfluous abstraction layers, code defending against situations that cannot arise, tests for impossible cases. So the review prompt should say explicitly to report only gaps that affect correctness or an explicit requirement and treat everything else as optional, and then you decide what is worth changing.

Five common failure modes and their fixes

Five days in, the potholes you have hit almost certainly fall into these five. The official best practices page lists them, and here they are again by how to recognize and how to solve each:

1. The grab-bag session. You asked about B while fixing A, then went back to A, and the window is full of unrelated debris while answer quality visibly drops. Fix: /clear between tasks.
2. Repeated correction. The same mistake survives two corrections, because every failed attempt stays in the context and keeps polluting it. Fix: after two misses, /clear and restart with a better prompt that absorbs the lesson.
3. An over-long CLAUDE.md. Too many rules, the important ones drowned, and it stops "listening." Fix: trim until you cannot; delete what it already does by default, and convert what must hold 100% of the time into a hook.
4. Trust without verification. It produces a plausible-looking implementation that misses an edge case, and you merge without noticing. Fix: always give it a verifiable check — tests, a script, a screenshot; never ship what you cannot verify.
5. Unbounded exploration. "Go investigate X" has no scope, so it reads hundreds of files and fills the window. Fix: state the scope of the investigation concretely, or hand it to a subagent with its own context.

Notice that three of the five are the same point: the context window is the scarcest resource. That is the sentence this course has been repeating since D2.

The Agent SDK: the same loop as Claude Code in 20 lines

The last topic connects the course back to D2. claude -p already looks a lot like a function call, but it is a command line — you assemble the arguments, parse the JSON, and manage the process yourself. If you want Claude Code's full set of capabilities (reading and writing files, running commands, searching code, hooks, subagents, permissions, sessions) inside your own program, there is a proper entry point: the Claude Agent SDK.

It is a different thing from the @anthropic-ai/sdk / anthropic package used on D2. The D2 SDK is a client for the Messages API: you send messages and it replies, with tools for you to define and the loop for you to write. The Agent SDK is Claude Code packaged as a library: file and Bash tools built in, the whole agent loop, context management, and the permission system, with you supplying one task and a set of options. Twenty lines gets you an agent that edits code:

import { query } from '@anthropic-ai/claude-agent-sdk'
 
// query returns an async iterator: each message is a piece of reasoning, a tool call, or the final result
for await (const message of query({
  prompt:
    'Add zod input validation to POST /todos in src/routes/todos.ts, write matching vitest cases under test/, and run until green.',
  options: {
    allowedTools: ['Read', 'Edit', 'Glob', 'Grep', 'Bash'], // pre-authorized tools
    permissionMode: 'acceptEdits', // file edits go unasked; Bash is still bound by allowedTools
    maxTurns: 20, // budget: 20 turns at most
    systemPrompt: 'You are a senior Node.js backend engineer. Edit only src/ and test/.', // the D1 business card
  },
})) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if ('text' in block) console.log(block.text) // its reasoning
      else if ('name' in block) console.log(`-> tool: ${block.name}`) // which tool it is calling
    }
  } else if (message.type === 'result') {
    console.log(`finished: ${message.subtype}`) // success / error_max_turns …
  }
}

import asyncio
 
from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ResultMessage, query
 
 
async def main() -> None:
    # query returns an async iterator: each message is reasoning, a tool call, or the final result
    async for message in query(
        prompt=(
            "Add pydantic input validation to POST /todos in app/routes/todos.py, "
            "write matching pytest cases under tests/, and run until green."
        ),
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob", "Grep", "Bash"],  # pre-authorized tools
            permission_mode="acceptEdits",  # file edits go unasked; Bash is still bound by allowed_tools
            max_turns=20,  # budget: 20 turns at most
            # the D1 business card
            system_prompt="You are a senior Python backend engineer. Edit only app/ and tests/.",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # its reasoning
                elif hasattr(block, "name"):
                    print(f"-> tool: {block.name}")  # which tool it is calling
        elif isinstance(message, ResultMessage):
            print(f"finished: {message.subtype}")  # success / error_max_turns …
 
 
asyncio.run(main())

The division of labor is now clear: for a question-answering, extraction, or define-your-own-tools model call, use the Messages API (D2); for an agent that works inside a file system, use the Agent SDK (today); to call it from a shell script, use claude -p. The same model sits underneath all three, and the difference is who provides the loop and the tools.

That is the end of the course. You can now brief it (D1), feed it material (D2), write the handbook and work through a plan (D3), install gates and procedures (D4), and let it run unattended while the parties check each other (D5). Two directions from here. To see how the same things are done on the OpenAI side — how Codex and the Agents SDK complete the same TODO API task and where the two differ — take the companion course Using Codex and the OpenAI Agents SDK Effectively, whose D5 runs a head-to-head comparison on today's task. To go deeper, the two things D4 touched briefly each have a seven-day course: mcp-7days (wiring tools into any agent) and agent-skills-7days (turning experience into reusable capabilities), both coming soon.

Source Reading

Hands-On Lab

The lab is a TS wrapper: it takes a diff (git diff main by default), assembles a claude -p command carrying the three locks, parses the JSON, and exits non-zero on an overrun or an error. Under MOCK=1 it does not really call claude but returns several fixed JSON scenarios, so readers without Claude Code installed can still finish and run the parsing and decision logic. solution/ci.py is the same thing in Python.

1. Run pnpm install in the starter directory, then MOCK=1 pnpm start, and see it print a not-yet-parsed placeholder output, confirming the skeleton runs.
2. Finish exercise 1: assemble the claude -p arguments in buildArgs — bare, output-format json, permission-mode dontAsk, max-turns, max-budget-usd, append-system-prompt.
3. Finish exercise 2: in parseResult, read is_error, subtype, num_turns, total_cost_usd, and result out of the JSON, and decide success or failure and whether the budget was exceeded.
4. Finish exercise 3: make all three MOCK_SCENARIO values (success / over-budget / error) produce the right exit code and log, then set the budget very low on purpose to exercise the over-budget branch.
5. If you have the claude command, drop MOCK and run it for real, inspecting the fields in review.json; then read .github/workflows/claude-review.yml and confirm the key comes from secrets and permissions grant only pull-requests: write.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward permission and cost control for headless mode in CI, why adversarial review works, and the division of labor between the Agent SDK and calling the API directly. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Run an unattended task with claude -p, and parse the --output-format json result to judge success or failure
• Run multiple parallel sessions with worktrees, and design a Writer/Reviewer dual-session adversarial review
• Write a 20-line minimal agent with the Agent SDK, and name the fix for five common failure modes
• Explain the division of labor between the Messages API, the Agent SDK, and claude -p
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

There is no tomorrow for this course, but there is a next course. Take the same example task to Using Codex and the OpenAI Agents SDK Effectively and see how it is done on the OpenAI side and how the two ways of working differ — not which is smarter, but how each is best managed. To turn the MCP and skills from D4 into crafts of their own, mcp-7days and agent-skills-7days are coming soon. Take with you the sentence these five days kept returning to: the context window is the scarcest resource, and a verifiable check is the watershed for using an agent well.