Claude Code automation

1 · From interactive to automated essential

Here's the moment this chapter is built for. You've spent a week pair-programming with Claude Code and it's genuinely good — but you're still the bottleneck. Every review, every formatting pass, every "run the tests before you commit" happens only when you remember to ask. The obvious next thought is the dangerous one: "what if it just ran on its own?" That instinct is right. The trap is doing it without a plan, and this chapter is the plan.

Think about the difference between a power drill and an assembly line. A drill is a tool you hold — powerful, but every action needs your hand on it. An assembly line is the same tools wired to triggers: a part arrives, a step fires, the result moves on, and it runs at 3am whether you're there or not. K1 handed you the drill. This chapter wires the line. The catch — and it's the whole reason this chapter has a "safe automation" section — is that an assembly line with no guard rails will happily mangle whatever you feed it, at full speed, unattended.

Why the shift matters more than it looks. Interactive Claude Code has a safety net you never notice: you. When it proposes something risky, it asks, and you're sitting there to say no. The instant it runs headless in CI or a git hook, that net is gone — nobody is watching to answer the prompt. So automation isn't just "the same thing, faster"; it's a different risk model. The common beginner mistake is to treat a pipeline like a chat window and wire Claude straight into something that can push code or reach production — then act surprised when an unattended run does exactly what it was allowed to. The skill you're building here is to automate the tedious and gate the dangerous, deliberately, in config rather than in good intentions.

K1 was you at the keyboard. Automation is Claude Code running without you — in a script, a git hook, or CI. Three mechanisms: headless mode, hooks, and slash commands.

2 · Headless mode essential

Before automation, Claude Code is a conversation; headless mode makes it a command. That one change is what lets everything else in this chapter exist. A conversation waits for you, remembers context, asks follow-ups. A command takes an input, does one job, prints an answer, and exits — which is exactly the shape every script, pipeline, and cron job already knows how to talk to. Headless mode is how you turn the chatty assistant into a well-behaved Unix citizen.

If you've ever used grep or sort, you already understand the mental model. Those tools don't open a window and chat — you feed them text on the way in, they emit text on the way out, and you chain them together with pipes: cat file | grep error | sort. Headless Claude Code slots into that same pipeline as just another filter. git diff | claude -p "review this" reads like plain English precisely because it is the same pattern: stdin in, stdout out, exit. The -p ("print") flag is the switch that says "don't open a chat — take this one prompt, answer it, and get out of the way."

Why the output format is the hinge. A human reading a review wants prose. A script reading a review wants fields it can branch on — did it find bugs, how many, of what severity. That's what --output-format json buys you: instead of paragraphs you get structured data your code can parse and act on, which is the difference between "print the answer" and "make a decision based on the answer." Every real automation in this chapter ultimately rests on that ability to consume Claude's output programmatically. The mistake to sidestep: don't try to regex facts out of free-form prose when a structured format exists — brittle text-scraping is the number-one reason home-grown Claude pipelines break the first time the wording changes. Flag names for output format do evolve, so treat the docs as the source of truth and verify before you depend on an exact spelling in production.

The -p flag runs one prompt and exits. With --output-format json you get structured output a script can parse — the basis of every automation.

headless.shclaude -p "Summarize what changed in the last commit"        # one-shot
claude -p "List any TODO comments added in this diff" --output-format json > todos.json
git diff | claude -p "Review this diff for security issues. Be concise."   # pipe context in

3 · Hooks — automate on events intermediate

Here's the uncomfortable truth about telling an AI to "always do X." You can write "always run the tests before you finish" into your prompt, and Claude will usually comply — usually. But "usually" is a word that has no place near a production repo. Models are probabilistic; on a long, messy task the instruction can slip, get crowded out, or be quietly deprioritised. Anything you truly need to happen every single time can't live in a request the model might forget. It has to live somewhere that isn't the model at all. That somewhere is a hook.

Think of a hook like the interlock on a microwave door. The manufacturer doesn't put a sticker on the front saying "please remember to stop the microwave before opening the door" and trust you to comply — they wire a switch that cuts the magnetron the instant the door opens, deterministically, no memory required. A hook is that switch for Claude Code: you register a shell command against a lifecycle event — before a tool runs (PreToolUse), after it runs (PostToolUse), when the session stops (Stop) — and the harness, not the model, runs your command when that event fires. The model can't skip it and can't forget it, because the model was never in charge of it.

Why this reframes what "reliable" means. Once you internalise that hooks are run by the harness, a clean division of labour appears: put judgement in the prompt (what to build, how to approach a problem) and put guarantees in hooks (format on every edit, test on every stop, log on every Bash call). The two don't compete — they cover different needs. The common mistake is the reverse of forgetting: cramming procedural must-happen steps into an ever-growing system prompt and wondering why compliance is flaky. If it must happen deterministically, it's a hook; if it needs the model's reasoning, it's a prompt. Keep that line clean and your automations stop being hopeful and start being dependable. (Event names and matcher syntax are worth confirming in the Claude Code docs — they're the kind of detail that changes across versions.)

A hook is a shell command the harness runs when an event fires (before/after a tool call, on session stop). Hooks turn "remember to run tests" into "tests always run."

settings.json{
  "hooks": {
    "Stop": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": "pytest -q || echo 'TESTS FAILED'" } ]}
    ],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": "echo \"$(date) bash call\" >> .claude/audit.log" } ]}
    ]
  }
}

4 · Advanced — model a hook dispatcher advanced

You've written a hook and it didn't fire. Now what? This is the moment hooks stop feeling like magic config and start feeling like a black box — and a black box you can't reason about is a black box you can't trust with your repo. The cure is to stop treating dispatch as mysterious and understand the actual rule the harness uses to decide what runs. Once you can predict it on paper, a silent hook becomes a two-second diagnosis instead of an afternoon of guessing.

The mechanism is simpler than the mystery suggests. Picture a bouncer at a club with a guest list organised by night. An event happens ("someone wants in on Friday"); the bouncer flips to the Friday page (that's keying by event), then checks each name against the tool trying to enter — some entries say "anyone" (the * matcher), others name a specific guest ("Bash", "Edit"). Everyone who matches gets waved through, in list order. That's the entire algorithm: look up the event, filter its entries by whether the matcher matches the tool, collect the survivors, run them in order. No hidden state, no priority tricks.

Why bother modeling it in code? Because a rule you can run is a rule you can no longer argue with. The lab below rebuilds this dispatcher in a dozen lines of Python, and the payoff is diagnostic superpower: given any event, tool, and config, you can compute exactly which commands fire before you ever launch Claude. The common confusion this clears up is the "why did two hooks fire?" surprise — matchers stack, so a * entry and a "Bash" entry both fire on a Bash call, because both match. It's not a bug; it's the collect-all-survivors step doing its job. Understanding that turns hook debugging from superstition into arithmetic.

How does the harness decide which hooks fire for an event? A matcher dispatch. Modeling it makes hook behavior predictable.

hook_dispatch.pyimport fnmatch

def fire_hooks(event, tool, hooks):
    """hooks: {event: [(matcher, command)]}. Return commands that fire."""
    fired = []
    for matcher, cmd in hooks.get(event, []):
        if matcher == "*" or fnmatch.fnmatch(tool or "", matcher):
            fired.append(cmd)
    return fired

hooks = {
    "PreToolUse": [("Bash", "audit.sh"), ("Edit", "format.sh")],
    "Stop": [("*", "pytest -q")],
}
print("before Bash:", fire_hooks("PreToolUse", "Bash", hooks))
print("before Edit:", fire_hooks("PreToolUse", "Edit", hooks))
print("on stop:    ", fire_hooks("Stop", None, hooks))

before Bash: ['audit.sh']
before Edit: ['format.sh']
on stop:     ['pytest -q']

5 · Slash commands — reusable prompts intermediate

Watch what happens to a great prompt over time. You craft the perfect code-review prompt — structured, specific, catches the things your team keeps missing. You use it, it works, you're pleased. Two weeks later you retype it from memory and it's a bit shorter. A teammate asks how you did it and you paste a slightly different version into Slack. Within a month there are five drifting copies and no canonical one. The prompt was valuable; the fact that it lived only in your head and your scrollback was the problem. Slash commands fix exactly that.

A slash command is the same idea as a saved recipe card versus cooking from memory. Cooking from memory, the dish drifts every time and nobody else can reproduce it. Write the recipe on a card and drop it in the shared box, and now anyone can pull it out and get the same result — and if you improve it, you improve the one card everyone reads. A slash command is that card: a Markdown file in .claude/commands/ whose filename becomes the command name (review.md → /review) and whose contents are the prompt that gets expanded when you type it. It turns a good prompt from personal folklore into shared, versioned infrastructure.

Why "it's just a file" is the whole point. Because the command lives as a file in the repo, it inherits everything your repo already gives you for free: it's committed, so it's version-controlled; it's reviewed, so changes get scrutiny; it's shared, so the whole team runs the identical review instead of six personal variants. That's the leap from "my clever prompt" to "our team standard." The mistake worth naming: don't keep reinventing your best prompts in the chat window — the second a prompt is worth typing twice, it's worth saving as a command so it stops decaying. Slash commands also support arguments and frontmatter (things like a description or allowed tools); those specifics are exactly the kind of thing to confirm in the Claude Code docs, since the directory and frontmatter keys can shift between versions.

A slash command is a saved prompt in .claude/commands/. Type /name and it expands — great for team-standard workflows like reviews.

review.md<!-- .claude/commands/review.md -->
Review the current git diff for:
1. Correctness bugs and edge cases
2. Security issues (injection, secrets, authz)
3. Missing tests
Group findings by severity. Cite file:line. Be concise — no praise.

6 · Advanced — CI integration advanced

This is where the four boxes from the opening diagram finally snap together. Up to now you've met the pieces in isolation — headless mode, hooks, commands. CI is the assembly line that runs them for real, without you, on an event you didn't personally trigger. Everything in this chapter was building toward being able to say: "on every pull request, a reviewer looks at the diff and leaves comments" — and have that reviewer be Claude Code, running itself.

The right way to picture the CI reviewer is as a tireless first-pass triage nurse, not the doctor. The nurse doesn't diagnose and discharge; they take vitals, flag the obvious red flags, and hand a cleaner case to the doctor. A CI review step does the same for your team: it catches the missing test, the hard-coded secret, the off-by-one — the boring, mechanical stuff a human reviewer resents having to spot — so that when a person opens the PR, their attention lands on the judgement calls that actually need a human. The map from the diagram is exact: the PR is the trigger, claude -p is headless mode, and the posted comment is the result feeding the pipeline.

Why the "never replaces human review" line is not a disclaimer but a design rule. The temptation, once the bot is catching real bugs, is to let it gate merges — to make its verdict binding. Resist that. An LLM reviewer is confidently wrong often enough that handing it a veto over your main branch trades one kind of risk for a worse one, and it does so silently. The pattern that ages well is advisory: it comments, a human decides, merge stays behind human approval. And because CI runs unattended with a real API key, this section is also the doorway to the safety concerns that dominate the rest of the chapter — the same run that can post a helpful comment could, if you let it, push a branch or hit an external system. Notice the key comes from encrypted secrets and never touches the workflow file; that discipline is the first of the guard rails the next sections make non-negotiable.

Put it together: on every PR, run Claude Code headless as a reviewer and post findings. It never replaces human review — it catches the obvious before a human looks.

claude-review.ymlname: Claude review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - env: { ANTHROPIC_API_KEY: "${{ secrets.ANTHROPIC_API_KEY }}" }
        run: |
          git diff origin/main...HEAD > /tmp/diff.txt
          claude -p "Review /tmp/diff.txt for bugs & security. Markdown, by severity." > review.md
          cat review.md   # or post as a PR comment via gh

7 · Professional — safe automation professional

Every earlier section quietly removed a safety net; this section puts a new one back. When you were at the keyboard, you were the guard rail — Claude proposed, you approved, and anything alarming stopped at your "no." Automation deletes that human in the loop by design. An unattended agent with broad permissions isn't a productivity tool anymore; it's a process that can push, deploy, delete, or spend money with nobody positioned to catch it. The power you built in sections 1–6 is real, and so is the blast radius. This section is where you bound it.

The right mental model is a bank cashier, not a locked vault. A vault that opens for nothing is safe but useless; a cashier is useful precisely because they can move money — under strict, pre-agreed limits. They can hand over cash up to a threshold, but a large withdrawal requires a manager's signature, and that rule holds whether or not the manager happens to be looking. Safe automation is built the same way: give the pipeline exactly the privileges the job needs and no more (least privilege), let it freely do the reversible, cheap things, and put a hard human gate in front of the irreversible ones — push, deploy, delete, refund. Crucially, that gate must be structural, enforced in permissions and config, not a polite instruction the model is trusted to honour.

Why "fail closed" is the load-bearing phrase. Systems face situations their author never anticipated, and the entire question is which way they lean when that happens. Fail open means "when unsure, proceed" — which in an unattended agent is how a novel edge case becomes a production incident. Fail closed means "when unsure, refuse and ask for a human" — the automation stops safely instead of guessing dangerously. Pair that default with an audit hook that logs every action, so that if something does slip through you have a record to reconstruct what happened. The mistake that burns teams is inverting the trust: assuming the agent will behave and bolting on safety after the first scare. Do it the other way round — assume no one is watching, block everything irreversible before the job starts, and treat any pipeline that can act on your repo with the same seriousness as production infrastructure, because that is exactly what it is.

Automated agents are powerful and unattended — so bound them: least-privilege permissions, no auto-push/deploy without a human gate, log every action (audit hook), and fail closed. Treat a pipeline that can act on your repo as production infrastructure.

auto_gate.pydef allow_automated(action, context):
    HARD_DENY = {"git push", "deploy", "delete", "issue refund"}
    if any(d in action for d in HARD_DENY) and not context.get("human_approved"):
        return False, f"'{action}' needs human approval in automation"
    return True, "ok"

print(allow_automated("run pytest", {}))
print(allow_automated("git push origin main", {}))
print(allow_automated("git push origin main", {"human_approved": True}))

(True, 'ok')
(False, "'git push origin main' needs human approval in automation")
(True, 'ok')

8 · Tech-lead — own the automation standards tech-lead

Everything so far, you could do for yourself. This section is about doing it for twenty people who won't read the docs. An individual engineer can hold "gate the dangerous stuff" in their head and mostly get it right. A team can't — not because they're careless, but because a standard that lives in one person's judgement is a standard that's already gone the moment they're on holiday. The tech-lead job isn't to be the person who remembers the safe pattern; it's to make the safe pattern the default, so that being careful requires no memory at all.

Think of it as the difference between a lifeguard shouting rules at a busy pool and a pool designed so the rules enforce themselves — a fence around the deep end, a gate that latches on its own, depth markers painted on the tiles. The shouting lifeguard scales to one pool on a quiet day; the design scales to every pool, every day, with no one shouting. A lead codifies automation the second way. The decisions are real ones — which hooks are mandatory, what CI is allowed to run Claude on, the unbending rule that irreversible actions need a human — but the art is encoding them into shared, version-controlled settings.json (hooks and permissions) and .claude/commands/, so the guard rails ship with the repo. A new hire clones the project and inherits the safe defaults without being told.

Why a written selector beats a wise leader. The genuinely hard call is which tasks earn full automation and which stay interactive, and "ask the lead" doesn't scale past the lead's attention. So make the criteria explicit: a task is safe to run headless only at the intersection of reversible, well-specified, and automatically verifiable — and any missing axis pulls it back to interactive, with a human gate if it's also irreversible. Writing that rule down converts your judgement into something the whole team can apply identically, tomorrow, without you. The failure mode to avoid is the heroic lead who is personally the safety system: it works right up until the day they're unavailable and someone ships an unguarded pipeline. Codify the standard, ship it in the repo, and the team automates the tedious and gates the dangerous by default — which is the entire point of this chapter, made durable.

A lead decides what's automated and where the human gates are: which hooks are mandatory, what CI runs Claude on, and the rule that irreversible actions always need a human. Codify it so the team automates safely by default.

# One-shot, non-interactive; prints the result to stdout and exits.
claude -p "Summarize the changes in the last commit" > summary.txt

# Pipe input in, capture output — composes like any CLI:
git diff | claude -p "Write a conventional-commit message for this diff"

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "pnpm prettier --write $CLAUDE_FILE" }
        ]
      }
    ]
  }
}

import re

def dispatch(event, tool, config):
    cmds = []
    for entry in config.get(event, []):
        if re.fullmatch(entry["matcher"], tool):
            cmds += [h["command"] for h in entry["hooks"]]
    return cmds

config = {"PostToolUse": [
    {"matcher": "Edit|Write", "hooks": [{"command": "prettier --write"}]},
    {"matcher": "Write",      "hooks": [{"command": "git add -A"}]},
]}
print(dispatch("PostToolUse", "Write", config))  # ['prettier --write', 'git add -A']
print(dispatch("PostToolUse", "Read",  config))  # []

# .claude/commands/review.md

Review the staged diff for:
1. Correctness bugs (logic, off-by-one, error handling).
2. Security issues (injection, secrets, unsafe deserialization).
3. Missing tests for changed behavior.

Report findings grouped by severity. Do not fix anything — report only.
Use `git diff --staged` to see the changes.

// settings.json (CI profile)
{
  "permissions": {
    "deny":  ["Bash(git push*)", "Bash(rm -rf*)", "Bash(gh pr merge*)"],
    "allow": ["Read", "Grep", "Bash(pnpm test)", "Bash(pnpm lint)"]
  }
}
// Plus: run in a sandbox/branch, require PR review before merge,
// and use a PreToolUse hook to block commits that touch secrets.

def automate(reversible, well_specified, has_automated_check):
    if not has_automated_check:
        return "INTERACTIVE — no automated way to verify the result"
    if not reversible:
        return "INTERACTIVE + human gate — irreversible action needs approval"
    if well_specified:
        return "HEADLESS — scriptable, verifiable, safe to run unattended"
    return "INTERACTIVE — task too ambiguous to automate reliably"

print(automate(True,  True,  True))    # HEADLESS (e.g. commit-message gen, lint fixes)
print(automate(False, True,  True))    # INTERACTIVE + human gate (e.g. deploys)
print(automate(True,  False, True))    # INTERACTIVE (ambiguous refactor)

Knowledge check check yourself