claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit shell-command background session launch syntax

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Dispatch new agents" and "From your shell" for shell-command background sessions

Current Documentation

The agent view page currently documents prompt-based dispatch from agent view:

Type a prompt in the input at the bottom of agent view and press Enter to start a new background session. The session is named automatically from the prompt; rename it later with Ctrl+R.

The same table lists prompt prefixes such as subagent names, @<repo>, /<command>, and pull request references, but does not list ! <command> as an agent-view input form.

The shell launch section documents --bg only with a prompt:

Pass --bg to start a session that goes straight to the background:

claude --bg "investigate the flaky SettingsChangeDetector test"

The CLI reference likewise documents --bg without --exec:

--bg | Start the session as a background agent and return immediately. Prints the session ID and management commands. Combine with --agent to run a specific subagent

What's Wrong or Missing?

Claude Code v2.1.154 added a user-facing way to start shell-command background sessions:

• In claude agents, type ! <command> to run a shell command as a background session that can be attached to and detached from.
• From the shell, use claude --bg --exec '<command>' for the same kind of command-backed background session.

The current docs cover ordinary prompt-based background sessions, regular interactive ! shell mode, and background Bash tasks inside a session, but they do not explain this new agent-view/shell entry point. Users reading the agent view page would not know that ! in agent view dispatches a shell command as a background session rather than a normal Claude prompt, or that --bg --exec exists for scripts.

This is separate from generic background task documentation because the new feature is specifically about creating a background session from a shell command and then managing it through the agent view lifecycle.

Suggested Improvement

Add ! <command> to the "From agent view" prefix table, for example:

! <command> | Run a shell command as a background session. The command appears in agent view so you can monitor it, attach to inspect output, and detach while it keeps running.

Add a shell example near the existing claude --bg examples:

claude --bg --exec 'npm test'

Clarify whether command-backed background sessions support the same management commands as other background sessions, such as claude attach <id>, claude logs <id>, and claude stop <id>.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 page sections affected

Version context: Claude Code v2.1.154 release entry: claude agents: type ! <command> to run a shell command as a background session you can attach to and detach from. Also available as claude --bg --exec '<command>'.