Run Claude Code in the background with claude --bg

Start a session, close the terminal, come back later: the commands, their limits, and how to keep it safe.

Claude Code can run a session in the background without you holding a terminal open. Start it with claude --bg, get a short id back, close the window, and come back later to read the output, attach to it or stop it. For a long task on a server this is a lighter alternative to wrapping the session in tmux. This guide covers the commands, what each one does, and the limits to keep in mind. Everything below was checked against Claude Code 2.1.328 with claude --help and a short test session; run the same help on your version.

Start a background session

cd ~/projects/my-app
claude --bg "Run the test suite, fix the failing tests, and summarize what you changed."

The command returns at once and prints something like this (the id is a short hex string):

backgrounded · 2b6153b4
  claude agents             list sessions
  claude attach 2b6153b4    open in this terminal
  claude logs 2b6153b4      show recent output
  claude stop 2b6153b4      stop this session

The session keeps working in the directory you started it in. Normal options apply, so you can pick the model and set a spend cap in the same call, for example --model sonnet and --max-budget-usd 5.

The five commands you need

After an update: respawn

A background session keeps running the Claude Code build it started with. After you update, claude respawn <id> restarts one session, or claude respawn --all restarts every one, so they pick up the current binary. Check that nothing important is mid-task before you do it.

Resume a finished session in the background

With --resume <session-id>, --bg continues that session in the background under the same id. If the session is already running, it starts a copy and says so, so you do not end up with two writers on one conversation without noticing.

Background session or tmux?

Neither one is a scheduler. For something that must start every night, use cron or a systemd timer with claude -p; the unattended-run guide shows that setup.

Safety

A short checklist

The handbook covers running Claude Code on a server long term: sessions, alerts, backups and rules for what the agent may never do: Pocket Server.