Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/headless
Section/Topic
claude -p stdin/exit behavior, especially when a turn launches a background Bash command
Current Documentation
The headless page currently says:
Non-interactive mode reads stdin, so you can pipe data in and redirect the response out like any other command-line tool.
It also documents follow-up -p invocations as one-shot commands:
Use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation.
And the CLI reference summarizes -p as:
claude -p "query" | Query via SDK, then exit
Separately, the Bash tool docs say:
For long-running processes such as dev servers or watch builds, Claude can set run_in_background: true to start the command as a background task and continue working while it runs. List and stop background tasks with /tasks.
What's Wrong or Missing?
The docs describe claude -p as a stdin-driven command that prints a result and exits, and they describe background Bash commands as long-running tasks, but they never explain how those behaviors interact in headless mode.
The v2.1.163 changelog entry says:
Fixed claude -p hanging forever after its final result when a backgrounded command never exits - background shells are now stopped ~5s after the result once stdin closes
That leaves one user-visible lifecycle gap in the docs:
A. Headless mode does not document what happens to lingering background shells after the final result
Users embedding claude -p in CI, scripts, or subprocess calls can reasonably infer from Query via SDK, then exit that the process ends once the final result is printed. They can also infer from the Bash tool docs that a background command may keep running. The docs never state which rule wins when a -p turn launches a background shell that outlives the answer.
After v2.1.163, Claude Code resolves that ambiguity by stopping background shells shortly after the final result once stdin closes, but the headless docs do not mention that cleanup behavior or when to prefer an interactive/background-session workflow instead.
Suggested Improvement
Add a short note to headless and cross-link it from the Bash tool docs.
Suggested wording:
In claude -p, background Bash commands are not intended to outlive the headless invocation indefinitely. After Claude prints the final result and stdin closes, Claude Code gives any background shell a short grace period, then stops it so the -p process can exit cleanly.
Also add a usage note such as:
If you need a long-lived dev server, watch process, or other background task that should survive beyond one printed result, use an interactive session, /tasks, or a background session instead of claude -p.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
Total scope: 3 pages affected
Version context: The missing lifecycle note became user-visible in Claude Code v2.1.163, which changed headless cleanup so a never-ending background shell no longer keeps claude -p hanging forever after the final result.
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/headless
Section/Topic
claude -pstdin/exit behavior, especially when a turn launches a background Bash commandCurrent Documentation
The headless page currently says:
It also documents follow-up
-pinvocations as one-shot commands:And the CLI reference summarizes
-pas:Separately, the Bash tool docs say:
What's Wrong or Missing?
The docs describe
claude -pas a stdin-driven command that prints a result and exits, and they describe background Bash commands as long-running tasks, but they never explain how those behaviors interact in headless mode.The v2.1.163 changelog entry says:
That leaves one user-visible lifecycle gap in the docs:
A. Headless mode does not document what happens to lingering background shells after the final result
Users embedding
claude -pin CI, scripts, or subprocess calls can reasonably infer fromQuery via SDK, then exitthat the process ends once the final result is printed. They can also infer from the Bash tool docs that a background command may keep running. The docs never state which rule wins when a-pturn launches a background shell that outlives the answer.After v2.1.163, Claude Code resolves that ambiguity by stopping background shells shortly after the final result once stdin closes, but the headless docs do not mention that cleanup behavior or when to prefer an interactive/background-session workflow instead.
Suggested Improvement
Add a short note to
headlessand cross-link it from the Bash tool docs.Suggested wording:
Also add a usage note such as:
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
claude -pusage and follow-up invocations, but not background-shell lifetime or cleanupclaude -pasQuery via SDK, then exitwithout any lifecycle caveatrun_in_background: trueand/tasks, but not how headless-pruns clean up lingering background shellsTotal scope: 3 pages affected
Version context: The missing lifecycle note became user-visible in Claude Code v2.1.163, which changed headless cleanup so a never-ending background shell no longer keeps
claude -phanging forever after the final result.