What you will be able to do
- Choose between /goal, /loop, cron tasks, cloud scheduled tasks and event triggers for a given unattended engineering task
- Write a goal condition that an evaluator can check, and predict how a goal ends on success, impossibility or error
- Predict how scheduled tasks behave across idle periods, missed fires, restarts and time zones
- Wire a CI, monitoring or GitHub event to an agent that acts as first responder
- Turn on file checkpointing for an Agent SDK or headless run, rewind its edits to a safe checkpoint, and name the edits a rewind cannot reach
Key concept
Trigger and stop condition — An unattended agent run has no human to start it or end it. Something must start each turn (a finished turn, a clock, or an event), and something must decide when to stop: a checkable condition, a cancellation, an expiry, or an error a human has to fix.
1.Three ways an agent works without you
An unattended agent does engineering work while nobody watches the terminal. Examples include migrating call sites overnight, grooming a backlog every weeknight, or picking up a CI failure at 10pm. Every one of these runs answers two questions a human would normally answer: when does the next turn start, and when does the work stop? If either answer is wrong, the run fails in a typical way. It stops after one turn with the job half done, or it keeps working long after the job is finished or has become impossible.
Claude Code gives you three ways to drive turns. Goal-driven work starts the next turn when the previous one finishes, and keeps going until a condition holds. Schedule-driven work starts on a clock. Event-driven work starts when something outside pushes in a message, such as a webhook, a pull request or an alert. You can also write your own continuation logic in a Stop hook. In that case your script, not an evaluator, decides when to stop.
| Approach | Next turn starts when | Stops when |
|---|---|---|
| /goal | The previous turn finishes (or an idle check-in or automatic retry comes due, interactively) | A model confirms the condition is met or judges it impossible, a turn fails on an error you must fix, or you run /goal clear |
| /loop | A time interval elapses | You stop it, or Claude decides the work is done |
| Stop hook | The previous turn finishes | Your own script or prompt decides |
Pick the approach that matches the shape of the work. A migration that is finished when every call site compiles fits a goal. Checking a deploy every five minutes fits a schedule. Reacting to a red build fits an event, because polling for a failure that has not happened yet wastes turns.
Checkpoint 1 of 6· Match them up
Match each unattended task to the approach that fits it best
Tap a term, then the definition that fits it.
Choose the approach by the shape of the work. A checkable end state fits a goal. A recurring check fits a schedule. A failure that arrives from outside fits an event, because polling for it wastes turns. A Stop hook lets your own logic, not an evaluator, decide when to stop.
“Reacting to events as they happen instead of polling: see Channels. Your CI can push the failure into the session directly.”Source: code.claude.com
2.Goal-driven runs and how they end
A goal is only as good as its completion condition. A model evaluates the condition after each turn, so the condition needs three parts. The first is one measurable end state, such as a test result, an exit code, a file count or an empty queue. The second is a stated check that says how Claude proves it, such as npm test exits 0. The third is the constraints that must hold along the way, such as "no other test file is modified". Without that last part, an agent can make the tests pass by changing tests nobody asked it to touch.
A goal like /goal all tests in test/auth pass and the lint step is clean gives the evaluator something to verify. Goals also work headless: claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" runs until the condition is settled. Running /goal with no argument shows the condition, how long the goal has been running, how many turns have been evaluated, the current token spend and the evaluator's latest reason. That makes the cost of a long goal visible while it runs.
After each turn the evaluator returns one of three verdicts. Not yet met: Claude keeps working and uses the evaluator's reason as guidance for the next turn. Met: the goal is cleared and an achieved entry is recorded. Impossible: the goal is cleared and a failed entry is recorded with the reason. Some errors also clear the goal, because only a human can fix them. These include an exhausted credit balance, a context overflow that auto-compaction couldn't clear, an unavailable model, and an authentication failure when Claude Code manages its own credentials.
Other failures leave the goal alive. If the failure tends to clear on its own, such as an overloaded server or a dropped connection, Claude Code retries and shows a Goal still active notice. After three automatic retries the goal pauses. If retrying would only repeat the failure, the goal pauses at once with a Goal paused notice that names the cause. Examples are an API rate limit, a usage limit, or a hook that ended the turn. Headless runs behave differently in one more way: in a -p session, progress check-ins arrive only at the end of a turn, never on an idle timer.
Checkpoint 2 of 6· Check yourself
A team leaves /goal the tests in test/auth pass running overnight. By morning the evaluator has recorded the goal as achieved, but Claude got there by loosening assertions in two existing test files. Which change to the goal would have prevented this?
A good condition has three parts: a measurable end state, a stated check, and the constraints that must hold along the way. Without the constraint, the evaluator accepts passing tests however they were reached. Running headless, checking status, or switching to a schedule doesn't change what the evaluator accepts as success.
“Constraints that matter: anything that must not change on the way there, such as “no other test file is modified””Source: code.claude.com
Sources1
3.Schedule-driven runs: session loops versus cloud tasks
Schedules come in two kinds, and they behave very differently when you walk away. /loop and the cron tools (CronCreate, CronList, CronDelete) schedule prompts inside a running session. Cloud scheduled tasks (formerly called routines) run on Anthropic-managed infrastructure against a fresh clone. Desktop scheduled tasks run on your own machine.
| Property | Cloud | Desktop | /loop |
|---|---|---|---|
| Requires machine on | No | Yes | Yes |
| Requires open session | No | No | Yes |
| Access to local files | No (fresh clone) | Yes | Yes |
| Permission prompts | Auto mode by default | Configurable per task | Inherits from session |
| Minimum interval | 1 hour | 1 minute when Claude sets it, 1 hour in the forms | 1 minute |
Session schedules only fire while Claude Code is running and idle. If you close the terminal, they stop firing. Backgrounding the session is different: it carries /loop tasks over to a background session that keeps running. Missed fires are not caught up. If Claude was busy through three scheduled times, the task fires once when it becomes idle. A fixed-interval loop you never cancel ends after seven days, which caps how long a forgotten loop can run. When you resume a session, cron tasks are restored, but a self-paced /loop is not and has to be started again.
A loop with no prompt runs .claude/loop.md if the project defines one. This gives a team a shared maintenance routine for the branch it is tending:
Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.Cloud tasks have their own rules. A custom cron expression that fires more than once an hour is rejected. A plain five-field expression is read in UTC, so 0 9 * * 1-5 runs at 9:00 UTC, not 9:00 local time. A run scheduled exactly on the hour can start several minutes late, so pick a time like 9:07 if timing matters. A nightly backlog task is the typical fit: it reads issues opened since the last run, labels them, assigns owners and posts a summary to Slack.
Checkpoint 3 of 6· Check yourself
During a long refactor, a session has /loop 10m check the deploy running. Claude is busy on one long request for 35 minutes, so three scheduled times pass. What happens to the loop?
Session schedules do not catch up on missed fires. When Claude becomes idle the task fires once, not once for each interval it missed, and the loop is not cancelled.
“If a task’s scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle”Source: code.claude.com
Checkpoint 4 of 6· Check yourself
A developer in New York (currently UTC−5) creates a cloud scheduled task with the custom cron expression 0 9 * * 1-5, then shuts their laptop for the week. When does the task run?
A cloud task reads a plain five-field expression in UTC, not local time. Cloud tasks run on Anthropic-managed infrastructure, so the laptop does not need to be on, and the limit is once per hour, not once per day.
“when the expression is five fields alone, write the hours in UTC, so 0 9 * * 1-5 runs at 9:00 AM UTC”Source: code.claude.com
4.Event-driven responders and CI first response
Event triggers let an external system start the agent instead of a clock. A cloud scheduled task can have an API trigger: an HTTP POST to the task's own endpoint, with a bearer token, starts a run, and the request body carries the event. It can also have a GitHub trigger that fires on pull request, release or issue events. Filters on author, base or head branch, labels, draft state or merged state keep it narrow. Examples: setting is draft to false skips drafts, and a needs-backport label filter runs a port only when a maintainer asks for it.
There are two other entry points. A Claude Code GitHub Actions workflow responds to @claude mentions and turns issues into pull requests inside your own CI. Channels push CI results, chat messages and monitoring webhooks into a session that is already running. Use a channel when the responder needs the local files and the debugging context that the session already holds. Use a cloud task when the work stands on its own and can start from a fresh clone.
CI incident first response combines these pieces. In the alert-triage pattern, a monitoring tool calls the task's endpoint when an error threshold is crossed. Claude pulls the stack trace, correlates it with recent commits, and opens a draft PR that links back to the alert, so on-call starts from a proposed fix. Anthropic's CI team runs a version of this with Claude Tag in its on-call Slack channel. Standing instructions are kept as skills in a Git repository, and MCP connectors reach Grafana, logs, PagerDuty, GitHub and Kubernetes. An orchestrator sends executor subagents to chase leads in parallel, and Claude posts the first situation report, typically within 15 minutes.
Checkpoint 5 of 6· Match them up
An on-call team wants several things to start an agent run, not a clock. Match each need to the entry point that fits it.
Tap a term, then the definition that fits it.
An API trigger lets an outside system such as a monitoring tool start a cloud task, and a GitHub trigger with filters starts one only on matching repository events. The GitHub Actions workflow answers @claude mentions inside your own CI. A channel is the choice when the responder needs a session's local files and debugging context, not a fresh clone.
“API: trigger on demand by sending an HTTP POST to the task’s own endpoint with a bearer token”Source: code.claude.com
5.Rewinding an unattended run's file changes
A file checkpoint is a snapshot of the files an agent edited, taken so the edits can be undone. Unattended runs need one more than interactive ones. When a nightly refactor breaks the build at 3am, nobody is there to press undo, so the harness that started the run needs a known-good state to put the files back to. Recording how far the work got is a separate job. A file checkpoint does not record progress. It only reverses edits.
Checkpoints come from prompts, not from tool calls. Every prompt that starts a turn creates one, and Claude Code keeps file snapshots for the 100 most recent checkpoints in a session. A tool result is not a prompt. So a single claude -p "Refactor the authentication module" that edits dozens of files has one restore point: the state before the run began. If you want restore points between stages, have the harness send the work as several prompts and keep the checkpoint of the last one that passed validation.
In the Agent SDK, file checkpointing stays off until you turn it on. Set enableFileCheckpointing: true (enable_file_checkpointing=True in Python). Also pass extraArgs: { 'replay-user-messages': null }, because without it the response stream does not carry the user-message UUIDs that identify each checkpoint. The harness captures the UUID of each prompt it sends and decides from its own signal when to revert, such as a failed validation or a red test run. It then calls rewindFiles(checkpointId). A shell script can rewind after the run has ended by resuming the session with the checkpoint's UUID:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>A rewind does not reach every edit. If a subagent edits a file the main conversation had not already touched, that edit survives the rewind. This includes a forked skill running in the background, which is the default. An orchestrator that sends executor subagents to apply fixes therefore needs version control to undo their work, so run unattended edits on a branch Git can reset. Snapshots also expire. Claude Code deletes them in a retention sweep about 30 days after the session last saved one, and a rewind to a checkpoint whose snapshots are gone can fail with No files were restored. Raise cleanupPeriodDays to keep them longer.
Checkpoint 6 of 6· Check yourself
A nightly Agent SDK job turns on file checkpointing, records the UUID of its prompt, and rewinds when validation fails. Afterwards, the files Claude edited itself are restored, but two config files that a background subagent changed still hold the subagent's edits. What explains this?
If a subagent edits a file the main conversation had not touched, rewinding leaves that edit in place, and version control has to undo it. The checkpoint, the replay option and retention all worked, because the main conversation's files were restored.
“The subagent’s edits to other files stay, so use version control, such as Git, to revert them.”Source: code.claude.com
Sources
(9)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/goalOfficial docs
“Claude keeps working until it’s met, a model judges it impossible, or an error you have to fix clears the goal.”
↩︎ Three ways an agent works without you“One measurable end state: a test result, a build exit code, a file count, an empty queue”
↩︎ Goal-driven runs and how they end“Constraints that matter: anything that must not change on the way there”
↩︎ Goal-driven runs and how they end“Not yet met: Claude keeps working and takes the reason as guidance for the next turn.”
↩︎ Goal-driven runs and how they end“After three automatic retries, the goal pauses instead.”
↩︎ Goal-driven runs and how they end“In a non-interactive session, such as one started with -p, this is the only way Claude Code delivers check-ins.”
↩︎ Goal-driven runs and how they end“Claude keeps working until it’s met, a model judges it impossible, or an error you have to fix clears the goal.”
↩︎ Key concept“Impossible: the evaluator judged that the condition can never be satisfied.”
↩︎ Prediction“Constraints that matter: anything that must not change on the way there, such as “no other test file is modified””
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/scheduled-tasksOfficial docs
“Reacting to events as they happen instead of polling: see Channels. Your CI can push the failure into the session directly.”
↩︎ Three ways an agent works without you“Tasks only fire while Claude Code is running and idle.”
↩︎ Schedule-driven runs: session loops versus cloud tasks“A loop you don’t cancel ends when seven days elapse.”
↩︎ Schedule-driven runs: session loops versus cloud tasks“No catch-up for missed fires.”
↩︎ Exam trap 2“If a task’s scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/routinesOfficial docs
“Expressions that run more often than once per hour are rejected.”
↩︎ Schedule-driven runs: session loops versus cloud tasks“API: trigger on demand by sending an HTTP POST to the task’s own endpoint with a bearer token”
↩︎ Event-driven responders and CI first response“On-call reviews the PR instead of starting from a blank terminal.”
↩︎ Event-driven responders and CI first response“when the expression is five fields alone, write the hours in UTC”
↩︎ Exam trap 1“when the expression is five fields alone, write the hours in UTC, so 0 9 * * 1-5 runs at 9:00 AM UTC”
↩︎ Checkpoint - 4.https://code.claude.com/docs/en/channelsOfficial docs
“a webhook from CI, your error tracker, a deploy pipeline, or other external service arrives where Claude already has your files open”
↩︎ Event-driven responders and CI first response - 5.https://code.claude.com/docs/en/github-actionsOfficial docs
“Run Claude Code in GitHub Actions workflows to respond to @claude mentions, automate tasks, and turn issues into pull requests”
↩︎ Event-driven responders and CI first response - 6.https://claude.com/blog/ai-ci-cd-on-callSecondary source
“Claude authored the first situation report in every recent incident that had one, typically publishing its first analysis within 15 minutes.”
↩︎ Event-driven responders and CI first response - 7.https://code.claude.com/docs/en/checkpointingOfficial docs
“Every prompt you send that starts a turn creates a new checkpoint”
↩︎ Rewinding an unattended run's file changes“Claude Code keeps file snapshots for the 100 most recent checkpoints in a session.”
↩︎ Rewinding an unattended run's file changes“The subagent’s edits to other files stay, so use version control, such as Git, to revert them.”
↩︎ Rewinding an unattended run's file changes“Rewinding to a checkpoint whose snapshots are gone can fail with No files were restored.”
↩︎ Rewinding an unattended run's file changes - 8.
“Update checkpoint at each prompt you send; a tool result isn't one”
↩︎ Rewinding an unattended run's file changes“Required to receive checkpoint UUIDs in the response stream”
↩︎ Rewinding an unattended run's file changes - 9.https://code.claude.com/docs/en/agent-sdk/typescriptOfficial docs
“enableFileCheckpointing | boolean | false | Enable file change tracking for rewinding”
↩︎ Rewinding an unattended run's file changes“enableFileCheckpointing | boolean | false | Enable file change tracking for rewinding”
↩︎ Exam trap 3