Your First Background Agent

You'll want a working sense of Define the Blast Radius before this lesson, since background agents run unsupervised and need a Tier 1 classification before you let them loose.

You have the inner loop, structured logs, a checkpoint, and a blast-radius classification. Now you combine all of it: you define the task, start the agent, walk away, and come back to a completed diff. That is the L8 payoff.

For Claude Desktop users: use the 'run in background' option in a new conversation, or simply start a long-running task and switch windows. Claude will continue working and notify you when done. For Claude Code users: the headless flag (claude --headless or -H) runs a session without the interactive UI. Pass the task as a prompt. The agent works. When it finishes, the result is in your git tree.

Git worktrees are the isolation layer. Instead of the agent working in your main checkout, a worktree creates a second checkout of the same repo in a separate directory. The agent works there. You work in the main tree. No conflicts. When it finishes, you review the diff and merge if it passes.

Here is the before and after: a JSDoc-coverage task runs in a worktree at ../project-jsdoc-agent created with git worktree add. The headless command runs claude with a prompt that names the directory, the spec criteria, and the test command. The agent edits 14 files, runs npm test, and reports 'JSDoc added to 14 functions in src/utils/. All 63 tests pass. No signatures changed. Spec: 4/4 criteria passed. Ready to review.' You review the diff once.

The right first task: a Tier 1 task with a passing test suite and a 3-5 criterion spec. Good candidates: generate JSDoc for all exported functions, add missing type annotations, apply a style fix across a directory. Bad candidates: anything Tier 2+, anything with ambiguous success criteria. The first run will feel anticlimactic. The agent runs, you check back, you review the diff. That anticlimactic feeling is the goal.

Paste this into Claude:

I want to run my first background agent task. Help me set it up: (1) Identify a Tier 1 task from my project that has a passing test suite and clear success criteria: [describe your project and a candidate task, e.g. 'generate JSDoc comments for all exported functions in src/utils/' or 'add missing type annotations to all functions in src/api/']. (2) Write the spec: 3-4 binary criteria the agent should verify before it is done. (3) For Claude Code: write the exact shell command to run this as a headless session, including how to capture output to a log file. For Claude Desktop: describe how to set up the task and let it run in the background. (4) Show me how to create a git worktree for this task so the agent works in isolation. Then walk me through reviewing the diff when the agent finishes.

What good looks like:

• You identified a Tier 1 task with a passing test suite and a written spec
• You created a git worktree and the agent ran inside it, not in your main checkout
• The agent completed without interactive prompts from you
• You reviewed the diff after the run and could evaluate it against each spec criterion
• The test suite still passes after the agent's changes

What a good response looks like:

Setup for first background agent run (Claude Code path):

```bash
# Create the worktree
git worktree add ../project-jsdoc-agent main

# Run headless session inside the worktree
cd ../project-jsdoc-agent
claude --headless \
  --output-format stream-json \
  'Add JSDoc comments to every exported function in src/utils/ that does not already have one. For each function: document params, return type, and a one-sentence description. Run npm test when done. Report pass/fail.' \
  2>&1 | tee agent-run.log
```

Spec verified by agent before reporting done:
1. STRUCTURAL: Only files in src/utils/ modified. (grep check: git diff --name-only | grep -v src/utils/)
2. BEHAVIORAL: All existing tests pass. (npm test exits 0)
3. COVERAGE: Every exported function with no existing JSDoc now has one. (grep -rn 'export.*function' src/utils/ | count vs JSDoc count)
4. NEGATIVE: No function signatures changed. (git diff src/utils/ | grep '^-export' should be empty)

Agent completion report:
'JSDoc added to 14 functions in src/utils/. All 63 tests pass. No signatures changed. Spec: 4/4 criteria passed. Ready to review.'

Your review: check the diff, run npm test once more after merge. Done.