Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / CLI flags

--bg

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 --background. 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-09-26.

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

In the changelogs

20

Releases whose published page names --bg.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

  7. 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

  8. 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

  9. 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

  10. 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

  11. 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

  12. 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

  13. v2.1.198
  14. v2.1.187
  15. v2.1.174
    --pool Backend Error Message

    found in this entry's text

  16. v2.1.172
  17. v2.1.166
  18. v2.1.166

    found in this entry's text

  19. v2.1.122
    Background Job Safety Guards

    found in this entry's text

  20. v2.1.121
    Disable Background Agents Fleet Setting

    found in this entry's text

First cited

8

The earliest release whose published evidence quoted --bg was v2.1.122, 28 Apr 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.12228 Apr 2026--bg with auto mode requires
v2.1.12228 Apr 2026--bg with bypassPermissions requires
v2.1.17210 Jun 2026--bg and --pool are different backends
v2.1.18723 Jun 2026--bg, --background
v2.1.1981 Jul 2026--bg and --print conflict
v2.1.2247 Aug 2026--bg and --environment are different backends. Use `claude -p '<task>' --environment <id>` directly to start a session on the environment.

2 further spans in the ledger name it. The list above is the earliest first and stops at 6.

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