How Claude Code background sessions work
Run Claude Code in the background with --bg, then use agents, logs, attach, stop, and rm with the short ID printed by the CLI.
Start a background session with claude --bg and save the short ID it prints. Use claude agents to list sessions, claude logs <id> to inspect recent output, and claude attach <id> to open one in your terminal. claude stop <id> ends the process but keeps its conversation; claude rm <id> removes the background record.
When to use it
Background mode separates the running agent from the terminal that launched it. That is useful for long checks or parallel tasks, but it introduces process lifecycle commands that do different things from conversation resume.
Use it safely
1. Launch and retain the ID
Name the work before backgrounding it, provide an explicit prompt, and record the short ID Claude prints. The command returns immediately while the agent continues.
claude --name integration-tests --bg "Run the integration suite and fix only deterministic failures."2. Inspect without attaching
List background agents when you lose the ID, then read recent terminal output. Logs are an observation surface; attaching is for interactive control.
claude agents
claude logs <id>3. Attach, stop, or remove deliberately
Attach to interact with a running session. Stop preserves its conversation for a later resume. Remove is cleanup for an exited background session and may also remove its worktree when Claude reports that is safe.
claude attach <id>
claude stop <id>
claude rm <id>Important distinctions
- Do not start multiple background agents in the same mutable working tree unless their file ownership is coordinated.
- Stopping a process is not the same as deleting conversation history; the saved session can still be resumed.
- Review the target ID before rm, especially when a background run owns a generated worktree.
Where Crowsnest fits
Crowsnest offers its own parallel-task and Crew coordination with visible ownership and worktree isolation. Claude's native --bg sessions remain useful CLI processes, but they are not silently adopted as Crowsnest Crew tasks.
Source and version
The exact text and flags on this page were checked against the installed Claude Code 2.1.286 binary on October 9, 2026. Version-specific behavior can change, so compare your own --help output before scripting around it. Official CLI documentation →
Reviewed from first-party CLI output and the released Crowsnest product source. No command on this page bypasses provider limits, billing, authentication, or native history rules.