How to run Claude Code background agents

Five ways to run Claude Code in the background

They differ in what has to stay running, and who starts the work.

Background tasks inside a session

Press Ctrl+B while Claude is running a Bash command or a subagent to send it to the background (twice in tmux), and keep talking to Claude. Claude can also start a command in the background on its own. Subagents Claude spawns run in the background by default.

Type /tasks to list running shells and subagents and check on them. In a local terminal session a background command has no time limit, but it stops when Claude Code exits. To run several agents side by side, see how to run multiple Claude Code agents.

Agent view: sessions that outlive the terminal

claude --bg "<prompt>" starts a session in the background and returns right away; /bg moves the session you're in to the background. A supervisor process runs them, so closing the terminal doesn't stop them, but shutting down or restarting the computer does, and an unattached idle session is stopped after about an hour.

claude agents opens the agent view; claude attach <id>, claude logs <id> and claude stop <id> manage one session. Agent view is a research preview, so the commands may change.

Run Claude Code headless with claude -p

1. Run one prompt and exit

   -p (or --print) runs Claude Code without the interactive interface and exits when it's done, with exit code 0 on success. You can also pipe input in.

   claude -p "List the failing tests and why they fail"
   cat error.log | claude -p "Explain this error"

2. Get output a script can read

   --output-format json returns the result with the session ID and metadata, including total_cost_usd, an estimate computed on your machine. stream-json (with --verbose) streams events as they happen.

   claude -p "Summarize this repo" --output-format json | jq -r '.result'

3. Allow only the tools it needs

   In headless mode nobody is there to approve a prompt. Since v2.1.302 a run with no mode set starts in Manual and denies anything that would need approval. Use --allowedTools for what it may do and --permission-mode dontAsk to deny the rest instead of waiting.

   claude -p "Run the test suite and summarize failures" \
     --permission-mode dontAsk --allowedTools "Read,Bash(npm test)"

4. Cap the run

   --max-turns stops after a number of agent turns, and --max-budget-usd at an estimated cost (it can overshoot a little). Both work only with -p.

   claude -p "Fix the lint errors" --max-turns 15 --max-budget-usd 3

5. Continue the same conversation later

   Save the session ID from the JSON output and pass it to --resume, or use --continue for the most recent session in the directory.

   id=$(claude -p "Start a code review of src/" --output-format json | jq -r '.session_id')
   claude -p "Now check the tests too" --resume "$id"

6. Run it on a schedule with cron

   Anthropic's docs don't include a cron example; this one uses only documented flags. Cron has a minimal PATH, so use the full path from which claude, and create the log folder first. Don't add --bare here: it skips your subscription login and needs an API key.

   # crontab -e: weekdays at 9:00
   0 9 * * 1-5  cd /path/to/repo && /path/to/claude -p "Summarize yesterday's commits and list new TODO comments. Do not edit files." --permission-mode dontAsk --allowedTools "Read,Bash(git log *),Bash(git diff *)" --max-turns 10 --output-format json >> "$HOME/logs/claude-daily.log" 2>&1

Source: Anthropic's headless mode docs

Permissions for unattended runs

• dontAsk plus an --allowedTools list is the locked-down choice: it denies anything not on the list.
• auto lets a classifier review each action instead of you. Anthropic notes it doesn't guarantee safety.
• acceptEdits approves file edits and simple file commands, but not other shell commands.
• bypassPermissions skips prompts and safety checks. Anthropic says to use it only in isolated containers or VMs without internet access, as it offers no protection against prompt injection.
• For rules that apply to every run in a project, put permissions.allow and permissions.deny in .claude/settings.json. Deny rules always win.

Cloud options: when your computer is off

• Cloud sessions: claude --cloud "<task>" runs on Anthropic's infrastructure from your GitHub branch and keeps going with the laptop closed. Send follow-ups with claude -p "..." --cloud <session-id>.
• Cloud scheduled tasks: created with /schedule or at claude.ai/code, they run on a schedule (at most hourly), from an API call or from GitHub events. Pro, Max, Ultra, Team and Enterprise; research preview.
• GitHub Actions: anthropics/claude-code-action@v1 with a schedule trigger. An OAuth token from claude setup-token uses your subscription; an API key is billed per token.

Give a background agent a standing job

Background tasks, agent view and cron all start work you've already decided on. Crewmark gives a Claude Code session an ongoing role instead: it wakes on a heartbeat during working hours, takes the next issue from a board and messages you when it's blocked.

1. Turn a session into an employee

   Pick a role and a goal in numbers, and run the setup command Crewmark gives you in Claude Code. That conversation becomes the employee.

2. Let the heartbeat start the work

   The Crewmark daemon wakes the session every 15, 30 or 60 minutes during its working hours, on the subscription you already pay for, and leaves it alone outside them.

3. Assign issues, answer messages

   Add work as issues on the board; the employee picks them up, comments as it goes and asks you when it needs a review. See what an AI employee is.

Claude Code background agent FAQ