Claude Code automation: pick the surface, then prove the result

Claude Code automation means letting Claude Code work with no human at the prompt: /goal, claude -p in scripts and CI, hooks, background sessions, dynamic workflows, cloud routines and the Claude Agent SDK. Each unattended run is only as safe as its permissions, and only as trustworthy as the machine check that decides whether its output merges.

This hub helps developers and tech leads pick a surface for each job Claude Code could finish alone, from a 200-file migration to a nightly dependency report, and check the result without reading every diff.

Which Claude Code surface should run your job?

Choose by trigger and location: a job needing your local database runs on your machine; one that runs while your laptop sleeps goes to CI or a routine.

Your job	Surface	Trigger	Read
Keep working until a check passes	/goal with a verifiable condition	You, once	Goal workflows
A script or CI step your code checks	claude -p --output-format json	Script or cron	Scripting Claude Code
A rule that must hold on every tool call	Hooks in .claude/settings.json	Lifecycle event	Hooks
A team procedure anyone can run	A skill, optionally in a plugin	/name or Claude’s choice	Custom commands and skills
A scoped specialist	A subagent in .claude/agents/	Delegation	Custom subagents
Several local tasks at once	claude --bg, watched in claude agents	You	Agent view
Dozens to hundreds of agents	A dynamic workflow, or /effort ultracode	You, or Claude’s plan	Dynamic workflows
Runs while your machine is off	A routine (/schedule, research preview)	Clock, HTTP call or GitHub event	Routines
Pull request review and fixes	anthropics/claude-code-action@v1	Workflow event	GitHub Actions
Your own program drives the agent loop	The Claude Agent SDK	Your code	Agent SDK
Steer a session from your phone	Remote Control and channels	You, or an event	Channels and Remote Control
Effort, MCP servers, worktrees	Session configuration	Setup	Advanced techniques

For the other tools, see the Codex and Cursor automation hubs and background and cloud agents compared.

In what order should you automate Claude Code?

Each step reuses what the previous one proved.

1. Run the task interactively until it succeeds twice, and note the command that proves it, such as npm test: that is your gate or /goal condition.

2. Run it headless with the narrowest permissions, a spending cap and JSON output. claude -p starts in Manual permission mode (auto mode on third-party providers or with telemetry off, from v2.1.285), and dontAsk denies every tool call that would prompt (reads in the working directories and read-only commands still run), so you list the commands the job needs:

   claude -p "Triage the failing tests in ci.log. Do not edit test files." \
     --permission-mode dontAsk \
     --allowedTools "Read" "Grep" "Glob" "Bash(npm test *)" \
     --output-format json --max-budget-usd 2.00 > triage.json
   jq -e '.subtype == "success" and .is_error == false
          and ((.permission_denials // []) | length == 0)' triage.json

3. Add a hook for every rule that must always hold, such as blocking writes to migrations/. Hooks hold even when the model ignores instructions.

4. Parallelise once one run is reliable: start each task with claude --bg --worktree <name>, one checkout per session.

5. Schedule it or move it to CI: a routine for cloud runs, claude-code-action for pull request events.

6. Reach for the Agent SDK last, when claude -p can no longer express the flow; driving agents from code compares the three vendors’ SDKs.

Copy-paste prompt: find your automation candidates

Read CLAUDE.md, the package.json scripts, .github/workflows/ and the last 50 commit
messages. List up to eight recurring chores Claude Code could run unattended here.
For each: the trigger, the files it touches, the existing command that proves the
result correct, the fitting surface (/goal, claude -p, hook, routine, GitHub Action
or dynamic workflow) and a risk level (low: read-only report; medium: opens a PR;
high: touches release or infrastructure). Rank chores with a proving command and
low risk first. Do not change any files.

Copy-paste prompt: write the run contract for one job

We want to run "weekly patch and minor dependency bump" unattended with claude -p.
Write the contract to docs/automation/dependency-bump.md:
1. The exact claude -p command: --permission-mode dontAsk, an --allowedTools list
   limited to the job, --output-format json, --max-budget-usd.
   No --dangerously-skip-permissions.
2. The jq check a wrapper runs on the JSON result before trusting it.
3. The CI gate that runs afterwards.
4. Stop conditions: a major version, a failing test or a lockfile conflict means
   "report and stop", not "fix".
Show me the file first.

How do you verify unattended Claude Code output without reading every line?

Trust gates, not summaries:

• A result your script checks. The wrapper fails unless subtype, is_error and permission_denials show a clean run. A /goal “met” verdict is a model’s judgement, not proof.
• Independent checks. CI reruns tests, type check and lint on the pushed branch; the agent cannot mark its own work green.
• A second reviewer. /code-review, or claude ultrareview from the shell (review automation).
• An audit trail. Archive the JSON output with the run.

A human signs off at the merge on that evidence bundle; evidence, not diffs explains the reviewer’s new job.

What breaks when Claude Code runs unattended?

Symptom	Cause	Recovery
A headless run stops early	dontAsk denied a needed tool	Read .permission_denials; add one narrow --allowedTools rule
/schedule returns “Unknown command”	ANTHROPIC_API_KEY overrides the claude.ai login routines need	Unset the key, or use claude.ai/code/routines
A goal reports “met” but CI is red	The evaluator judged the conversation	Name a command and exit code in the condition; let CI decide
Spend keeps climbing	No cap on a headless run	Pass --max-budget-usd (-p only); see cost control
A teammate’s run behaves differently	They are on a different version or channel (stable is v2.1.287 and latest v2.1.296 on 2026-10-12; v2.1.283 is used here)	Compare claude --version; pin one channel
A PR-triggered job leaks a secret	The contributor’s hooks or MCP servers ran with the job’s secrets	Run with --bare --setting-sources "" --strict-mcp-config; check out the contributor’s commit into a separate directory the agent only reads, with trusted scripts from the default branch; see agent identity and secrets

Keep bypass mode out of unattended runs

Use --dangerously-skip-permissions only in a disposable, network-restricted sandbox with no secrets. For broad changes, --permission-mode auto keeps a classifier reviewing each action; see permissions and sandboxing.

Where to go next with Claude Code automation

• Prerequisite: configuration and settings files.
• Worked example: from issue to pull request with no hands on the keyboard.
• Share a proven procedure: plugins and marketplaces.
• Govern it org-wide: enterprise integration.