Background Agents & Autonomous Loops

The single-subagent lesson was about delegating inside one session to keep your context clean. This lesson is the opposite frame: work that runs while you're not watching, possibly for hours, possibly in the cloud, and the surfaces that let you supervise it rather than babysit it.

Two axes organize everything here:

• Session-scoped vs durable. Session-scoped work (/goal, /loop, background Bash, Monitor) lives and dies with a Claude Code session — close the laptop and it's gone (or restored only under narrow --resume rules). Durable work (cloud routines) runs on Anthropic infrastructure and survives your machine being off entirely.
• Local vs cloud. Agent view, /loop, and /goal are local — they run on your machine under a per-user supervisor. Routines are cloud. The Monitor and PushNotification tools are local helpers; PushNotification can reach your phone via Remote Control.

The one screen that ties the local side together is agent view (claude agents): a dashboard that lists every background session grouped by state, so you can see what needs you at a glance instead of scrolling transcripts.

                 unattended work in Claude Code
   ┌───────────────────────────┬───────────────────────────┐
   │        SESSION-SCOPED      │          DURABLE          │
   │  (dies with the session)   │   (survives laptop off)   │
   ├───────────────────────────┼───────────────────────────┤
   │ /goal   condition-chasing  │                           │
   │ /loop   cron / self-paced  │   routines (/schedule)    │
   │ background Bash + Monitor  │   schedule / API / GitHub │
   │ supervised in: agent view  │   managed at: claude.ai   │
   └───────────────────────────┴───────────────────────────┘
         LOCAL (your machine, a daemon)        CLOUD

Most of these surfaces are brand-new and research preview or experimental. Treat exact flags as moving targets and confirm against /help and the live docs for your installed version.

Open it with claude agents (research preview, v2.1.139+). It takes over the terminal and lists every background session — across all your projects — grouped into three buckets: Needs input, Working, and Completed, with pinned sessions and the ones that need you floated to the top. Narrow to one project with --cwd <path> (v2.1.141+); other launch flags include --model, --permission-mode, and --agent.

Navigation is keyboard-driven:

You dispatch new work two ways. From the dispatch input at the bottom of agent view, type a prompt and press Enter (each prompt starts its own new session — it's not a follow-up). Or from your shell:

# dispatch a background Claude session
claude --bg "investigate the flaky SettingsChangeDetector test"

# name it, or run a specific subagent as the session's main agent
claude --bg --name "flaky-test-fix" "..."
claude --agent code-reviewer --bg "address review comments on PR 1234"

To run a shell command as a background PTY job instead of a Claude session, type ! <command> in the agent-view input, or from the shell use claude --bg --exec '<command>':

claude --bg --exec 'pytest -x'

Manage sessions from your shell with: claude attach <id> (open in this terminal), claude logs <id> (read output), claude stop <id>, claude respawn <id> (--all), and claude rm <id>. Session IDs live under ~/.claude/jobs/. One gotcha: you can't open agent view while in-flight background tasks exist in your current session — check /tasks first.

Two pieces of machinery make background work safe and durable on your machine.

Worktree isolation. A background session starts in your working directory, but before its first file edit Claude moves it into an isolated git worktree under .claude/worktrees/. Parallel sessions can all read the same checkout, but each writes to its own worktree — so two background agents never clobber each other's edits. The move is skipped if you're not in a git repo, if you're already in a worktree, or if the write lands outside the cwd. Disable it entirely with worktree.bgIsolation: 'none' (v2.1.143+). Note: claude rm keeps a worktree that has uncommitted changes (and deleting from agent view removes the worktree including uncommitted changes — commit or push first).

The supervisor (daemon). Background sessions don't live in your terminal — a per-user supervisor process hosts them, separate from any terminal window. That's why a session keeps running after you close the tab. Key lifecycle facts:

• Unpinned idle sessions stop after ~1 hour (pin with Ctrl+T to keep them).
• On a binary update, the supervisor restarts pinned sessions automatically.
• Session state persists on disk through auto-updates, supervisor restarts, and machine sleep.

When things stall, two commands diagnose and recover:

claude daemon status                          # diagnose the supervisor
claude daemon stop --any --keep-workers       # restart the daemon, preserve sessions

--keep-workers is the important flag: it bounces the supervisor without killing the sessions it's hosting, which is how you clear a stuck daemon without losing in-progress work.

/goal <condition> (v2.1.139+) tells Claude to keep working across turns until a condition is met, instead of stopping when work merely looks done. For example:

/goal all tests in test/auth pass and lint is clean
/goal the build is green, or stop after 20 turns

It supports turn or time bounds ("…or stop after 20 turns"). /goal with no argument shows the current goal; /goal clear removes it. A goal is not session-scoped in the /loop sense — it's context-driven and resumes on --resume if still active.

The crucial detail is how the condition is evaluated. After each turn, a small fast model (typically Haiku) checks whether the goal is satisfied — but it evaluates from the transcript only. It cannot run shell commands or read files independently. So the condition must be provable from Claude's own output.

That reframes how you write goals. "All tests pass" is only checkable if Claude actually ran the tests and the passing output is in the transcript. A goal like "the code is correct" or "no bugs remain" is unverifiable — the evaluator has no way to confirm it from text. Make the success signal something Claude prints.

/loop [interval] [prompt] runs a prompt or slash command on a recurring schedule within the current session (alias /proactive). Both arguments are optional, and that's where the flexibility lives:

• Interval can be a bare token (30m, 5s, 2h, 7d) or a phrase ("every 2 hours"); seconds are rounded to the nearest minute. Omit the interval and the loop is self-paced — Claude picks delays between 1 minute and 1 hour, and can delegate to the Monitor tool for event-driven reactions instead of fixed polling.
• Omit the prompt and /loop runs a built-in maintenance prompt, or your custom .claude/loop.md (project, takes precedence) / ~/.claude/loop.md (user) — plain Markdown, 25KB max, edits apply on the next iteration.

/loop 5m /babysit-prs          # run a slash command every 5 minutes
/loop every 2 hours check CI and summarize failures
/loop                          # self-paced; uses built-in or .claude/loop.md

Scope and limits: session-scoped; recurring tasks have a 7-day expiry; max 50 concurrent scheduled tasks per session; press Esc to stop while it's waiting. Loops are restored on --resume/--continue only if a recurring task is under 7 days old (or a one-shot's time hasn't passed) — background Bash and Monitor tasks are never restored.

Under the hood /loop uses the scheduler tools CronCreate(cron_expression, prompt, recurring), CronList(), and CronDelete(task_id). The cron expression is a standard 5-field form (minute, hour, day-of-month, month, day-of-week) supporting *, ranges (1-5), steps (*/15), and lists (1,15,30). There is no extended syntax — L, W, ?, and MON/JAN aliases are not supported. When both day-of-month and day-of-week are constrained, either matches (vixie-cron semantics). A jitter offset means recurring tasks can fire up to 30 minutes late (or half the interval if under 1h) and one-shots up to 90s early — use non-round minutes to dodge it. Disable the scheduler entirely with CLAUDE_CODE_DISABLE_CRON=1.

When the work must outlive your session, use routines — created with /schedule [description] (alias /routines; subcommands list | update | run). A conversational setup captures the prompt, repos, environment, triggers, connectors, and permissions, and the routine runs on Anthropic's cloud. Edit them on the web at claude.ai/code/routines.

Routines have a minimum interval of 1 hour and support three trigger types:

Routines run autonomously — no permission prompts. Their reach is bounded by the configured repos, branch-push settings (branches are prefixed claude/ by default), environment network access, and connectors. There's a daily run cap per account; one-off runs are exempt from the cap but still consume usage. On Bedrock/Vertex/Foundry, /schedule is unavailable, and bare /loop with no prompt falls back to a fixed 10-minute schedule with no self-pacing.

For event-driven reactions you don't need a polling loop at all. The Monitor tool (v2.1.98+) streams a background process's output line-by-line into the conversation so Claude reacts the instant something appears — tail a log, watch CI, observe a directory. It uses Bash permissions (and respects Bash deny rules) but is not available on Bedrock/Vertex/Foundry, nor with telemetry disabled. The PushNotification tool sends a desktop/phone alert at a milestone (phone via Remote Control). List and stop background Bash + Monitor streams with /tasks (alias /bashes).