{"name":"--bg","slug":"bg","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Start the session as a [background agent](\/docs\/en\/agent-view) and return immediately. Prints the session ID and management commands. Combine with `--exec` to run a shell command as a background job instead of a Claude session, or with `--agent` to run a specific subagent. Checks [workspace trust](\/docs\/en\/permissions#project-allow-rules-and-workspace-trust) for the directory before it starts. Can't be combined with `-p`\/`--print`; see the [error reference](\/docs\/en\/errors#command-line-errors)","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":null,"removed_in":null,"in_current_build":false,"newest_mined":"2.1.308","builds":0,"mined_builds":149,"first_cited":{"version":"2.1.122","released_at":"2026-04-28 17:35:53","spans":8}},"aliases":["--background"],"entries":[{"version":"2.1.299","anchor":"bg-refuses-when-the-flag-cannot-be-told-from-prompt-text","heading":"claude --bg refuses to start when the flag is mixed into the prompt","line":"If Claude Code cannot tell `--bg` apart from the prompt text, it now starts nothing and tells you to put the flag first","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text"},{"version":"2.1.286","anchor":"background-session-workspace-trust-and-gate-blocked-reasons","heading":"Background sessions that fail to start now say what blocked them","line":"When a background session is blocked from starting, Claude Code now records whether a disclaimer or the folder trust check stopped it","released_at":"2026-09-30 17:14:38","reason":"found in this entry's text, named in this entry"},{"version":"2.1.285","anchor":"desktop-flag-rejected-when-combined-with-background-or-wor","heading":"New --desktop flag, and background commands now accept options in front of them","line":"`--desktop` opens the Claude Desktop app and now errors when combined with background or worktree options","released_at":"2026-09-29 17:32:09","reason":"found in this entry's text"},{"version":"2.1.285","anchor":"headless-cli-argument-classification-list","heading":"Changed list of startup flags Claude Code singles out","line":"Claude Code now keeps a set of startup flags, including `--print`, `--background` and `--version`, that it treats as a group","released_at":"2026-09-29 17:32:09","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"agents-can-now-take-a-file-path-instead-of-inline-json-bu","heading":"--agents can now take a file path instead of inline JSON, but only in print mode","line":"--agents now accepts a path to a file of subagent definitions, but only with --print (-p); interactive sessions still need inline JSON","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"background-sessions-started-from-a-trusted-home-directory-no","heading":"Background sessions started from a trusted home directory now carry that trust, with a warning when it is lost","line":"Background sessions started from a trusted home directory keep that trust, and warn you when they lose it","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"bg-rejects-agents-given-as-a-file","heading":"--bg rejects --agents given as a file","line":"Using --bg with --agents pointing at a file now fails; pass the agents as inline JSON instead","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text"},{"version":"2.1.257","anchor":"background-bg-can-now-resume-a-session-in-place","heading":"--background \/--bg can now resume a session in place","line":"Combining --bg with --resume now continues that session in the background under the same ID.","released_at":"2026-09-01 17:15:33","reason":"found in this entry's text"},{"version":"2.1.257","anchor":"cli-bg-dispatch-telemetry-gains-cwd-gone-reason","heading":"cli_bg_dispatch telemetry gains cwd_gone reason","line":"Background dispatch telemetry records a missing working directory as its own reason.","released_at":"2026-09-01 17:15:33","reason":"found in this entry's text"},{"version":"2.1.251","anchor":"bg-help-now-names-the-commands-that-take-the-printed-id","heading":"--bg help now names the commands that take the printed id","line":"--bg help now names attach, logs, stop and rm as the commands taking the printed id.","released_at":"2026-08-28 15:34:26","reason":"named in this entry, found in this entry's text"}],"entries_total":20,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"admin-setup","title":"Set up Claude Code for your organization","documented":false},{"source":"claude-code","path":"agent-view","title":"Manage multiple agents with agent view","documented":false},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"claude-tag","title":"claude-tag","documented":false},{"source":"claude-code","path":"env-vars","title":"Environment variables","documented":false},{"source":"claude-code","path":"errors","title":"Error reference","documented":false},{"source":"claude-code","path":"headless","title":"Run Claude Code programmatically","documented":false},{"source":"claude-code","path":"network-config","title":"Enterprise network configuration","documented":false},{"source":"claude-code","path":"permission-modes","title":"Choose a permission mode","documented":false}],"docs_total":13,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/bg","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}