Claude Code Automation: Setup, Failure Modes, Guardrails
9 min läsning
Key takeaways
- Claude Code automates four categories beyond code edits: repo edits and MRs, browser tasks via MCP, GitHub operations, and chained multi-step workflows.
- Every automation type has a predictable failure mode, and each one is prevented by a specific guardrail such as screenshot evidence, scoped PATs, or branch restrictions.
- Persist state outside the agent in a tracker and git checkpoints so a failed chain resumes instead of restarting and re-paying for tokens.
- Give each parallel session its own git worktree; agents sharing a checkout overwrite each other's uncommitted changes.
- Write acceptance criteria the run can self-check, like passing tests or a clean lint exit, before attempting an unattended run.
Claude Code automation goes beyond code edits: it can drive browsers, run GitHub operations, and chain multi-step tasks unattended, but each automation type fails in a predictable way that a specific guardrail prevents. This walkthrough covers the setup for each type, the named failure mode, and the hook, permission rule, or acceptance criterion that stops it, for teams running parallel sessions across repos.
What can Claude Code automate beyond code edits?
Claude Code covers four automation categories: repo edits and merge requests, browser tasks, GitHub operations, and chained multi-step workflows. Each has its own setup and its own failure mode, covered in the sections below.
Repo and PR automation
The default mode. Claude Code reads your repo, makes edits across files, runs tests, and opens a merge request with a summary. Teams running parallel agents pay per session, so cost per MR matters: one three-person team runs up to thirty Claude Code and Codex sessions and pays roughly $8 per merge request at API prices (their writeup). We broke down our own per-run math in coding agent costs.
Browser automation
Through MCP servers, Claude Code can drive a browser: fill forms, verify a staging deploy, screenshot a broken page. Configuration lives in your MCP settings alongside permissions.
Chained multi-step workflows
Hooks let you trigger steps automatically: run a linter after each edit, block a finish if tests fail, hand off to the next agent. The chain is where agents drift, which is why state tracking and acceptance criteria matter more here than in any single-task run.
How do you set up browser automation with Claude Code?
Configure an MCP browser server
Claude Code automates browsers through MCP browser tools: a server that exposes navigate, click, fill, and screenshot actions as callable tools. Add the server to your MCP config, restart the session, and confirm the tools appear before chaining it into a workflow. Give the agent the target URL, the acceptance criteria, and a hard step budget in the prompt. Without a step budget, a single browser task can burn through your token budget on retries.
Failure mode: the agent asserts success without evidence
The dangerous failure is silent. The agent reports "form submitted" when the click missed, the selector matched a stale element, or the page never loaded. In a chained workflow, that false success propagates: the next step runs against bad state, and you find out hours later in a merge request that should never have opened. Stale selectors are the usual root cause on any page that renders dynamically.
Guardrail: screenshot-or-it-didn't-happen
Make every browser task end with a screenshot saved to disk, and require the agent to reference the file path in its final report. Treat a task without a screenshot as failed and re-run it. For unattended runs, this pairs with state tracking: log each step's screenshot and assertion so a human can audit the chain in one pass. Aerunit's stories for coding agents apply the same rule across a fleet: an agent's claim of success is a hypothesis, not a result, until evidence exists. The honest limit: screenshots prove a page state, not business logic, so keep assertions about data in the test suite, not in the agent's own report.
How do you automate GitHub workflows with Claude Code?
Three GitHub operations automate well in headless mode: turning an issue into a pull request, replying to review comments, and fixing CI failures. Anthropic documents the headless/CI setup and the GitHub Actions integration in the Claude Code documentation, which covers running non-interactively with --print and wiring a PAT into Actions.
Scope permissions before you scope the task
Decide what the agent may touch before writing the prompt. In practice that means a scoped fine-grained PAT (contents: read/write, pull requests: write, nothing else), --allowedTools limited to git, gh, and your test runner, and --disallowedTools covering git push --force patterns and issue deletion. The permission list is the real task spec; the prompt is secondary.
Failure mode: the confident wrong fix
The common CI-fix failure is an agent that makes the test pass by changing the test, or by suppressing the assertion. It reports success, the merge request looks green, and the regression ships. This is the same "chaotic intern" pattern teams report after an hour of unsupervised running (dev.to).
Guardrail: branch and label restrictions
Restrict the agent to a agent/* branch prefix, require human approval to merge, and have it label its own PRs agent-authored so review filters catch them. We apply the same branch-prefix and label rules to agent runs in Aerunit, and we fall short in one place worth admitting: we do not yet block test-file edits automatically, so that guardrail stays a convention your prompt must enforce. More on permission patterns in our blog.
How do you structure a multi-step Claude Code automation workflow?
Split the thinking from the doing
Run two phases. First, a planning session that reads the repo and writes a task with explicit acceptance criteria. Second, execution sessions that receive one task each and are told not to redesign anything. The planning agent decides what; the execution agents only decide how within the constraints. This is the split that keeps an unattended agent from wandering off into a big codebase and refactoring half of it because it looked untidy.
Use your tracker as the task queue
Write the plan into Linear (or any issue tracker) as tickets with acceptance criteria, affected files, and dependencies. Each Claude Code run picks one ticket, works it, and closes it with a merge request. The tracker, not a chat transcript, is the source of truth. That means a session that dies mid-task leaves a visible, resumable artifact instead of a lost terminal. If you want a comparison of how queueing differs across tools like Cursor Cloud Agents and Vibe Kanban, see cloud coding agents compared.
State tracking and retries
A long paragraph on one idea: the difference between a chain that restarts and a chain that resumes is where state lives. If each step's output exists only in the previous session's context window, any failure means re-running the whole chain and paying for the tokens again. So persist state outside the agent: commit checkpoints to a branch, write intermediate results to files, and update the ticket status at every boundary. A retry then reads the ticket, checks the branch, sees which acceptance criteria already pass, and continues from the first failing one. On a fleet of parallel agents across multiple repos, this is also what stops two agents from picking up the same ticket or overwriting each other's work, because the tracker records claims. Budget for retries explicitly: if a task fails twice, mark it blocked and route it to a human rather than letting a third attempt burn your token budget arguing with itself.
How do you run several automations in parallel without losing track?
Parallel Claude Code runs fail at the coordination layer, not the model layer. One agent waits on an approval prompt nobody sees; another burns an hour on the wrong file. As one practitioner running four agents puts it, "Leave four alone together and they overwrite each other's work, duplicate each other, and burn your token budget arguing about who is right" (secondshiftdev on dev.to).
One worktree per agent
Give each session its own git worktree. Agents that share a checkout fight over the same files and stomp each other's uncommitted changes. With worktrees, each run has an isolated branch and directory, and merges happen on your terms. This is the baseline; without it, nothing else matters.
Watching a fleet of sessions
| Signal | What it tells you |
|---|---|
| Session state | Running, blocked, or finished |
| Waiting-on | Approval prompt, question, or retry |
| Token spend | Which run is eating the budget |
| Branch/MR | What each agent is actually touching |
A terminal tab shows none of this. The Ticksly team, running up to thirty Claude Code and Codex sessions, describes the problem directly: "With that many terminal tabs you lose track fast."
Where an orchestrator layer helps, and its limits
Aerunit sits above your sessions and surfaces per-agent state, waiting-on, and token spend, with instant feedback when an agent needs you (instant feedback for coding agents). It does not pick your task distribution strategy, fix a weak model's context handling, or replace Cursor Cloud Agents or Vibe Kanban's execution layer. It makes the fleet visible so you can intervene before an agent spends three hours on the wrong thing.
What are the common failure modes in Claude Code automations and how do you prevent them?
Unattended runs fail in five recurring ways: drift (the agent wanders off the task), overwrite conflicts (two parallel agents edit the same files), token burn (retries and re-reading eat the budget), silent waits (the run blocks on an approval prompt nobody sees), and false success reports (the agent claims done when acceptance criteria are unmet).
Each has a direct guardrail. Drift: pin the task to written acceptance criteria and re-inject them into the prompt each step. Overwrites: isolate agents in separate git worktrees and merge through one queue. Token burn: cap retries and set a hard budget per run. Silent waits: run with permission prompts pre-approved or a daemon that surfaces pending approvals. False success: require the agent to output a diff and a checklist against the criteria, not a prose summary.
The hard limit is context, not tooling. As one practitioner put it in a thread on agent orchestration for multi-repo development, "the real bottleneck isn't usually the orchestrator though - it's whether your small model can actually maintain context and make good decisions across multiple steps." Budget your runs accordingly.
How do you keep an automated Claude Code run on target without supervision?
Write acceptance criteria the agent can self-check
Vague instructions are how an agent spends three hours fixing the wrong thing. Convert each task into checks the run can execute itself: failing tests, lint rules, a build that must pass, a grep that must return nothing. "The title is the question" is a task; "all 42 tests in auth/ pass and npm run lint exits clean" is a target. If you cannot write the check, the task is not ready for an unattended run.
Hooks for instant feedback
Claude Code hooks let you run shell commands on events like post-tool-use and stop, so the run gets feedback in seconds instead of at the next human check-in. Wire a hook to run your test suite after every edit and pipe failures back into the session. This is the cheapest guardrail you have: the agent learns it broke something immediately, not after burning your token budget wandering.
Human gates, not constant supervision
You cannot watch thirty terminal tabs, and you should not. Route approval prompts to a human only at defined gates: before a merge request opens, before a force push, before touching migrations or auth. Everything between gates runs on the acceptance criteria and hooks alone. The failure mode to accept honestly: a gate you forgot to define is a decision the agent makes alone, so audit your gates after every incident, not just your prompts.
FAQ
What do Reddit threads say about orchestrating these agents?
The recurring theme is that orchestration is not the bottleneck. In a thread on agent orchestration for multi-repo development, one practitioner argued the real constraint is whether the model maintains context and makes good decisions across multiple steps. Posts also warn that parallel agents left alone duplicate work and overwrite each other, which matches the worktree-per-agent setup above.
How much does running parallel Claude Code sessions cost?
Cost scales with session count and retries. One three-person team running up to thirty Claude Code and Codex sessions reports roughly $8 per merge request at API prices. Retries and re-reading files are the main budget drain, which is why a hard token cap per run and a two-failures-then-block rule appear in the guardrails.
Do I need an orchestrator tool to run multiple agents?
No, but you need visibility. Separate git worktrees, a tracker as the task queue, and pre-approved permission prompts cover the baseline. What a terminal cannot show you is which session is blocked, waiting on approval, or burning tokens, so an orchestrator layer earns its place once you run enough sessions that checking each tab stops being realistic.