Follow Discord
Sweep 10 Nov 2026 · 02:18Z Build v2.1.322 539 read Stable v2.1.311 Latest v2.1.322 Next v2.1.322 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / CLI flags

--background

cli never mined documented JSON

A Claude Code CLI flag, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.

Also written --bg. Every list on this page counts all of these spellings together.

Start the session as a background agent 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 for the directory before it starts. Can't be combined with -p/--print; see the error reference

Anthropic's own wording. Read off CLI reference, captured 2026-11-09.

First seen — never in a mined build
Last seen — never in a mined build
Builds0 / 161on this box, as of v2.1.322
Written about v2.1.121 first named in a changelog, 27 Apr 2026

In the changelogs

24

Releases whose published page names --background.

  1. v2.1.321
    Settings for user delegated sessions are passed on, and some commands refuse to run in them

    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

    found in this entry's text

  2. v2.1.314
    Signing in can now be refused by your organisation's settings

    After signing in, Claude Code now checks your organisation's settings first and discards the login if they refuse it

    found in this entry's text

  3. v2.1.314
    New hidden --agents-view-if-allowed command-line flag

    Claude Code has a new hidden command-line flag, --agents-view-if-allowed, listed next to --bg and --background

    found in this entry's text

  4. v2.1.312
    Background session commands wait for a sign-in refresh before exiting

    The logs, attach, respawn, rm and stop commands, and --bg, now wait for any sign-in refresh to finish before exiting

    found in this entry's text

  5. v2.1.299
    claude --bg refuses to start when the flag is mixed into the prompt

    If Claude Code cannot tell --bg apart from the prompt text, it now starts nothing and tells you to put the flag first

    found in this entry's text

  6. v2.1.286
    Background sessions that fail to start now say what blocked them

    When a background session is blocked from starting, Claude Code now records whether a disclaimer or the folder trust check stopped it

    found in this entry's text, named in this entry

  7. v2.1.285
    New --desktop flag, and background commands now accept options in front of them

    --desktop opens the Claude Desktop app and now errors when combined with background or worktree options

    found in this entry's text

  8. v2.1.285
    Changed list of startup flags Claude Code singles out

    Claude Code now keeps a set of startup flags, including --print, --background and --version, that it treats as a group

    found in this entry's text

  9. v2.1.281
    --agents can now take a file path instead of inline JSON, but only in print mode

    --agents now accepts a path to a file of subagent definitions, but only with --print (-p); interactive sessions still need inline JSON

    found in this entry's text

  10. v2.1.281
    Background sessions started from a trusted home directory now carry that trust, with a warning when it is lost

    Background sessions started from a trusted home directory keep that trust, and warn you when they lose it

    found in this entry's text

  11. v2.1.281
    --bg rejects --agents given as a file

    Using --bg with --agents pointing at a file now fails; pass the agents as inline JSON instead

    found in this entry's text

  12. v2.1.257
    --background/--bg can now resume a session in place

    Combining --bg with --resume now continues that session in the background under the same ID.

    found in this entry's text

  13. v2.1.257
    cli_bg_dispatch telemetry gains cwd_gone reason

    Background dispatch telemetry records a missing working directory as its own reason.

    found in this entry's text

  14. v2.1.251
    --bg help now names the commands that take the printed id

    --bg help now names attach, logs, stop and rm as the commands taking the printed id.

    named in this entry, found in this entry's text

  15. v2.1.224
    Clearer error when --bg and --environment are combined

    Combining --bg and --environment now explains they are different backends and shows the right command.

    named in this entry, found in this entry's text

  16. v2.1.224
    Start a cloud session on a self-hosted environment with --environment

    Start a cloud session on your own environment with claude --environment, plus hidden --ref and --on-branch companions.

    found in this entry's text

  17. v2.1.198
  18. v2.1.187
  19. v2.1.174
    --pool Backend Error Message

    found in this entry's text

  20. v2.1.172
  21. v2.1.166
  22. v2.1.166

    found in this entry's text

  23. v2.1.122
    Background Job Safety Guards

    found in this entry's text

  24. v2.1.121
    Disable Background Agents Fleet Setting

    found in this entry's text

First cited

1

The earliest release whose published evidence quoted --background was v2.1.187, 23 Jun 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.

ReleaseDateThe span that was quoted
v2.1.18723 Jun 2026--bg, --background

Presence across releases

0

The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.

Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.

Feedback