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
claude agentsopens a list of your sessions. With--jsonit prints the active ones, interactive and background, as a JSON array and exits, which works without a terminal and suits scripts. Each entry has the fieldscwd,kind,name,pid,sessionId,startedAtandstatus. Add--allto include finished background sessions, and--cwd <path>to show only those started under a path.claude logs <id>prints the recent terminal output of a session. It is the raw terminal screen, including colour and cursor escape sequences, so on a plain shell it looks noisy. Pipe it through a tool that strips escape codes, or attach instead.claude attach <id>opens the session in your terminal as if you had started it there. The left arrow returns to the agent view and Ctrl+Z drops back to your shell. The session keeps running either way. A part of the session name works in place of the id.claude stop <id>stops a session. Its conversation is kept, andclaude attach <id>picks it up again later.claude rm <id>removes a session from the list and, if it is safe, deletes its worktree. The conversation is kept and still shows up inclaude --resume. Unlikestop, it also works on sessions that have already exited. If the worktree holds unpushed commits or uncommitted changes,rmrefuses and prints a value you must pass back to--discard-unpushedto confirm; that is deliberate.
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?
- Background session: you want a task to run while you do something else, you want a list of what is running, and you do not need to see the screen all the time.
attachis there when you do. - tmux: you want a normal terminal you can share, script with
send-keys, or restore the layout of after a reboot. The tmux guide on this site shows the workflow.
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 background session has nobody watching by default. Give it a narrow permission mode and a deny list before you start it, and a hook for the commands that must never run. A prompt you cannot see is a prompt that blocks the session until you attach.
- Set
--max-budget-usdon anything long, and look atclaude agentsnow and then. A forgotten session is still a session. - Clean up with
claude rmwhen a task is done, so old worktrees do not pile up.
A short checklist
claude --bg "task"from the project directory, with a budget cap.claude agentsto list,claude logs <id>to peek,claude attach <id>to take over.claude stopkeeps the conversation;claude rmfrees the list and the worktree.claude respawn --allafter an update.- Narrow permissions, deny rules and a hook in place before you walk away.