Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Background-session docs omit `--bg --name` post-spawn confirmation output

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Code Example

> claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"
>

---

> backgrounded · 7c5dcf5d
>   claude agents             list sessions
>   claude attach 7c5dcf5d    open in this terminal
>   claude logs 7c5dcf5d      show recent output
>   claude stop 7c5dcf5d      stop this session
>
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"From your shell" in the background sessions / agent view docs

Current Documentation

The docs currently say:

Pass --name to set the session's display name in agent view instead of the auto-generated one:

claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

After backgrounding, Claude prints the session's short ID and the commands for managing it:

backgrounded · 7c5dcf5d
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

The CLI reference also says:

--bg starts the session as a background agent and returns immediately, printing the session ID and management commands.

--name sets a display name for the session.

What's Wrong or Missing?

For the v2.1.144 change, these pages do not say that claude --bg --name <label> also echoes the chosen name in the immediate post-spawn confirmation.

The current agent-view example shows a named background launch, but the output block only shows the short ID. That makes it look like the name is visible only later in agent view, /resume, or the terminal title, instead of also appearing right after the session is spawned.

Suggested Improvement

Update the background-session docs so the --bg --name flow shows the current confirmation output.

At minimum:

  1. Revise the agent-view example so the sample confirmation includes the echoed session name along with the short ID.
  2. Add one sentence to the CLI reference clarifying that combining --bg with --name includes the name in the immediate confirmation output.
  3. Note that this behavior applies to the v2.1.144 change so readers know the output differs from older versions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/agent-view287-300Shows claude --bg --name ... but the sample post-spawn output only includes the short ID and management commands
https://code.claude.com/docs/en/cli-reference59, 87Documents --bg output and --name separately, but not that the confirmation output includes the chosen name when both flags are used together

Total scope: 2 pages affected

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#agent execution#callback error#memory management#API rate limit#retriever error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING