{"name":"--background","slug":"background","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Start the session as a [background agent](https:\/\/code.claude.com\/docs\/en\/agent-view.md) 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](https:\/\/code.claude.com\/docs\/en\/permissions.md#project-allow-rules-and-workspace-trust) for the directory before it starts. Can't be combined with `-p`\/`--print`; see the [error reference](https:\/\/code.claude.com\/docs\/en\/errors.md#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.322","builds":0,"mined_builds":161,"first_cited":{"version":"2.1.187","released_at":"2026-06-23 17:55:41","spans":1}},"aliases":["--bg"],"entries":[{"version":"2.1.321","anchor":"user-delegated-session-env-vars-forwarded-to-shellcommand-e","heading":"Settings for user delegated sessions are passed on, and some commands refuse to run in them","line":"Two user delegated session variables are passed to spawned processes, and `--bg` and `plugin eval` refuse to run when the direct API one is set","released_at":"2026-11-09 19:02:47","reason":"found in this entry's text"},{"version":"2.1.314","anchor":"login-flow-checks-org-config-and-reloads-org-documents","heading":"Signing in can now be refused by your organisation's settings","line":"After signing in, Claude Code now checks your organisation's settings first and discards the login if they refuse it","released_at":"2026-10-30 00:12:56","reason":"found in this entry's text"},{"version":"2.1.314","anchor":"new-hidden-cli-flag-agents-view-if-allowed","heading":"New hidden --agents-view-if-allowed command-line flag","line":"Claude Code has a new hidden command-line flag, `--agents-view-if-allowed`, listed next to `--bg` and `--background`","released_at":"2026-10-30 00:12:56","reason":"found in this entry's text"},{"version":"2.1.312","anchor":"cli-background-subcommands-wait-for-oauth-refresh-before-exi","heading":"Background session commands wait for a sign-in refresh before exiting","line":"The logs, attach, respawn, rm and stop commands, and `--bg`, now wait for any sign-in refresh to finish before exiting","released_at":"2026-10-27 18:36:10","reason":"found in this entry's text"},{"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"}],"entries_total":24,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"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":"admin-setup","title":"Set up Claude Code for your organization","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\/background","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}