Automation: headless Claude Code, CI, and the Agent SDK
Everything so far assumed a human in the loop. The next capability tier removes that assumption: the same Claude Code harness, running non-interactively — in CI, on a schedule, behind a webhook, or embedded in your own product. This is where "Claude helps me code" becomes "Claude is part of our infrastructure", and the engineering discipline shifts accordingly.
Headless mode: the harness as a CLI program
claude -p "your prompt" runs a full agentic session and exits — no interaction, output to stdout, machine-readable formats available (--output-format json when a program consumes the result, streaming JSON when you want progress). Two flags define the safety envelope: an explicit tool allowlist (--allowedTools) so the run can only do what the job needs, and the permission mode, which in automation contexts means either pre-approving exactly the safe operations or running fully sandboxed where nothing outside the container can be harmed. The mental model: headless mode turns "a task I would brief Claude on" into "a program I can call" — and everything programmable can be scheduled, triggered, and composed.
What that unlocks, concretely: nightly dead-code sweeps that open a PR with findings; a webhook that triages each new issue — reproduce, label, draft a fix if trivial; log-anomaly summaries every morning; documentation regenerated whenever the API schema changes. Each is the same shape: a well-specified brief, a narrow tool allowlist, an artifact out, a human reviewing the artifact.
Claude Code in CI: the review that never sleeps
The highest-value automation for most teams is agentic review on every pull request — via the GitHub integration or a headless invocation in your pipeline. The craft, learned the hard way by every team that has shipped this: give the reviewer a rubric (what classes of issue to hunt — correctness, security, performance — and what to ignore), have it report everything with severity and confidence attached rather than self-filtering — models told "only report serious issues" investigate just as hard and then silently drop real findings — and filter in a second cheap pass or by a human. Post findings as PR comments; humans keep the merge button. The same pattern generalises: CI-failure triage that annotates the failing run with a diagnosis, release-notes drafting from the merged diff, migration checks on every schema change.
The Agent SDK: the harness as a library
When the automation outgrows "run a CLI in CI" — you want an agent inside your product, with your UI, your state, your deployment — the Agent SDK (Python and TypeScript) exposes the Claude Code harness programmatically: the agent loop, the built-in file and shell tools, permission callbacks your code answers, session management, hooks, subagents, MCP connections. You write a query with options; the SDK runs the loop and streams you the events.
The decision boundary, stated once and worth memorising: raw Messages API when Claude is a component — a call inside your logic, tools you fully define; Agent SDK when Claude is the worker — an autonomous loop with file, shell, and search capabilities that you'd otherwise rebuild badly from scratch. Support triage bots, codebase-aware assistants, document-processing pipelines, internal ops agents — the SDK is the production chassis for all of them, with the guardrail surfaces (permissions, hooks, allowlists) already engineered.
The autonomy discipline
Removing the human from the loop removes the safety net you didn't know you were relying on, so the guardrails lesson's rules graduate from advice to law. Brief completely — an unattended agent can't ask clarifying questions; the prompt must carry goal, constraints, and definition of done. Bound everything — turns, tokens, wall-clock, and tool allowlists sized to the job, so no run is unbounded in any dimension. Demand evidence — the run's output must include what was verified and how ("tests pass" with the output attached, not asserted); narrated success is not success. Land artifacts, not actions — automation writes branches, PRs, drafts, and reports for human judgment; it does not merge, deploy, send, or delete on its own until the evaluation lesson's data says it has earned each specific privilege. And log the full trace, because with nobody watching, the trace is the only witness.
What to take into the next lesson
Headless mode makes the harness callable; CI makes it ambient; the Agent SDK makes it embeddable; the autonomy discipline makes all three safe. You now hold every tool this course has to offer. The next lesson assembles them into the big picture the whole second half has been building toward: the software lifecycle, re-drawn with AI in every stage.