New

Background & Cloud Agents

Until now, Claude only worked while you watched. A background agent

Background Agent

An agent task that keeps running while you do something else, instead of blocking your session. In Claude Code, `Ctrl+B` sends running tasks to the background, and skills can opt in with the `background` frontmatter field. When the work moves off your machine entirely, it's usually called a cloud agent.

"Like putting a load in the washing machine. You don't stand there watching; you come back when it beeps."

runs without you at the keyboard: in a script, in CI, or in a cloud

Cloud Agent

A coding agent that runs on remote infrastructure against your repository, so it keeps working after you close your laptop and usually finishes with a branch or pull request. Examples: Claude Code on the web (claude.ai/code, or `claude --cloud "task"` from the terminal, with `/teleport` to pull a session down), GitHub Copilot's cloud agent, and Cursor's cloud agents.

"Like hiring a remote contractor with their own workshop. You send the job, they send back the finished piece."

VM that keeps going after you close the laptop. It's like going from doing chores yourself to leaving a to-do list for a house sitter. Great leverage, as long as you check the work when you get home.

1The five ways to run Claude unattended

Headless claude -p

Your machine or CI runner

Scripts, pre-commit checks, one-shot jobs in pipelines

GitHub Actions

GitHub-hosted runners

@claude in issues/PRs, automated review, repo-event jobs

Cloud sessions

Anthropic-managed VMs

Hand off a task and close the laptop; run several at once

Routines

Anthropic-managed VMs

Recurring or triggered work: nightly triage, PR review, alert follow-up

/loop

Your open CLI session

Quick polling while you're at the keyboard

Cloud sessions and routines need a Pro, Max, Team, or eligible Enterprise plan, and they draw from the same usage limits as your interactive sessions.

2Headless mode: claude -p

Headless mode

Headless Mode

Running Claude Code non-interactively with `claude -p "prompt"`. Add `--allowedTools` to pre-approve tools, `--output-format json` (or `stream-json`) for machine-readable output, and `--bare` for CI. Perfect for scripts, GitHub Actions, and other automation.

"Like leaving a note for your assistant instead of having a conversation. They do the task and leave the results."

runs one task and exits, like any Unix command. It reads stdin, writes stdout, and returns a non-zero exit code on failure, so it drops into scripts and CI.

Terminal

# one-shot question
claude -p "What does the auth module do?"

# pipe data in, redirect the answer out
cat build-error.txt | claude -p "concisely explain the root cause of this build error" > output.txt

# let it act, but only with the tools you name
claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"

Machine-readable output

Terminal

# JSON with the text in .result, plus session_id and a cost estimate
claude -p "Summarize this project" --output-format json | jq -r '.result'

# force a shape with a JSON Schema; read it from .structured_output
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Use --bare in CI

By default, claude -p loads everything an interactive session would: CLAUDE.md, hooks, skills, plugins, and the project's MCP servers. Even in a folder you've never trusted, with no prompt. --bare skips all that auto-discovery, so every machine gets the same result and a random repo's hooks can't run. It's the recommended mode for scripts and will become the default for -p. Bare mode doesn't use your subscription login, so set ANTHROPIC_API_KEY.

Terminal

claude --bare -p "Summarize README.md" --allowedTools "Read"

Headless runs start in Manual permission mode, so anything not covered by --allowedTools or your allow rules gets denied rather than hanging. Grant the minimum: a docs-summary job doesn't need Bash. Chain runs with --continue or --resume <session_id>.

3Claude in GitHub Actions

The anthropics/claude-code-action GitHub Action runs Claude Code inside your workflows. Two modes: mention @claude in an issue or PR comment and it responds, or give it a prompt and it runs on any GitHub event, including a cron schedule. Fastest setup, from inside Claude Code in your repo (needs the gh CLI, logged in):

Claude Code

/install-github-app

It installs the Claude GitHub App, stores a secret (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN), and opens a PR with the workflow. Or do it by hand:

.github/workflows/claude.yml

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Pass CLI flags through claude_args, for example claude_args: "--max-turns 5 --model claude-sonnet-5". --max-turns plus a workflow timeout is your runaway-cost insurance. Only users with write access can trigger runs, and bots are rejected unless you allow them, which keeps bots from triggering Claude in a loop.

4Cloud sessions and routines

Claude Code in the cloud

A cloud session runs in an isolated, Anthropic-managed VM. Start one from claude.ai/code , the Claude mobile app, or the terminal. It clones your GitHub repo, works on a branch, and keeps running when you close the laptop.

Terminal

# plan locally, commit + push the plan, then execute in the cloud
claude --permission-mode plan
claude --cloud "Execute the migration plan in docs/migration-plan.md"

# several independent tasks at once
claude --cloud "Fix the flaky test in auth.spec.ts"
claude --cloud "Update the API documentation"

# pull a cloud session (and its branch) back into your terminal
claude --teleport

The VM clones your GitHub remote at your current branch, not your local checkout. Push first.
Cloud sessions don't load plugins from your local settings, and network access is limited to an allowlist by default. Configure env vars and setup scripts in the cloud environment.
In a local session, Ctrl+B backgrounds running tasks so you can keep typing.

Routines
Routine (Scheduled Agent)
A Claude Code cloud agent that runs automatically on a trigger: a schedule (at most hourly), an API call, or a GitHub event like a new pull request. Set one up at claude.ai/code/routines or with `/schedule` in the CLI. Routines are a research preview as of Sep 2026. For repeating work only while a session is open, there's `/loop`.
"Like a cron job with a brain. Instead of running the same script, it runs a whole agent with instructions."
research preview

A routine is a saved prompt + repos + connectors that runs as a cloud session on a trigger: a schedule (hourly at most often), an HTTP call to its /fire endpoint, or a GitHub event such as a pull request or release. Manage them at claude.ai/code/routines or from the CLI:

Claude Code

/schedule daily PR review at 9am
/schedule in 2 weeks, open a cleanup PR that removes the feature flag
/schedule list

Routines run fully autonomously, with no approval prompts. They push to claude/-prefixed branches, and anything they do through GitHub or connectors shows up as you. So scope them tightly: remove every connector the routine doesn't need, and write the prompt so success is unambiguous ("open a draft PR and post the link in #eng", not "look into the backlog"). A green run status only means it didn't crash; open the run to see what it actually did.

Need something recurring only while you work? /loop 5m check if the deploy finished runs in your open session and stops when you close it.

5Hand off, or stay interactive?

Hand it off when

The task is well-defined and you can say what "done" looks like.
There's a check that proves it: tests, type-check, build, a lint rule.
It's repetitive: dependency bumps, doc drift, flaky-test fixes, triage.
You already made the design decisions (a plan file exists).
It would otherwise block your laptop for an hour.

Stay interactive when

You're still deciding what to build.
It needs taste: UI feel, copy, product calls.
It touches auth, payments, migrations, or production data.
It needs local-only things: uncommitted work, local services, a device.
You can't describe how you'd verify the result.

Good pattern: explore and plan interactively in plan mode, commit the plan, then send the execution to the cloud.

6Review discipline for agent PRs

Background agents turn you from author into reviewer. That's the job now, so do it properly. An agent PR deserves more scrutiny than a teammate's, not less: it was written by something that never ran your app in a browser.

CI must be green before you read a line. Tests, type-check, build. If the agent can't get it green, it's not done.
Check scope first. Does the diff only touch what the task needed? Unrelated "cleanups" are where bugs hide.
Read the tests it wrote. Agents love tests that assert the code does what the code does. Look for real expectations.
Hunt the danger zones. Lockfiles, env handling, auth checks, SQL, anything in proxy.ts, deleted tests, disabled lint rules.
Click through the preview. A preview deployment
Preview Deployment
An automatic staging environment created for every pull request or branch. Lets you see and test changes before merging to production.
"Like a dress rehearsal before opening night. See exactly how it looks before going live."
is the fastest way to catch "compiles but broken."
Keep branch protection on. Agents open PRs; humans merge them. Never let an unattended agent push to main.

7Common traps

Vague prompts

An unattended run can't ask a clarifying question. "Improve performance" gets you a 40-file diff. Say what to change, what not to touch, and how to prove it worked.

Too many tools and connectors

Routines can use every tool from every included connector, writes included, without asking. Headless runs do whatever --allowedTools permits. Grant the minimum.

Secrets in the wrong place

Never commit API keys into workflows. Use GitHub Secrets and the cloud environment's settings, and remember environment variables there are visible to anyone who uses that environment.

Unbounded runs

Parallel cloud sessions share your rate limits. In CI, set --max-turns and a job timeout.

Treating fire payloads as trusted

Text sent to a routine's /fire endpoint arrives labeled as untrusted data. Keep it that way: it's a prompt injection surface.

Rubber-stamp merges

Ten green agent PRs a day is how subtle bugs get in. If you can't review it, don't schedule it.

Docs: Headless mode · GitHub Actions · Cloud sessions · Routines

Next steps

Unattended agents are only as safe as the guardrails around them. Set those up next.

Hooks & Automation Parallel Agents Prompt Injection & Security Deployment Checklist