claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit recovery guidance for an unresponsive background service

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Manage sessions from the shell," "The supervisor process," and the background-session troubleshooting guidance for claude agents / claude logs <id>

Current Documentation

The docs currently say:

claude agents — Open agent view

claude logs <id> — Print the session's recent output

claude daemon status — Print the supervisor's state, version, socket directory, and worker count

To inspect this state without reading the files directly, run claude daemon status. It reports whether the supervisor is reachable, its process ID and version, the socket directory, and how many background sessions are live.

The generic troubleshooting page also says:

Command hangs or freezes

If Claude Code seems unresponsive:

1. Press Ctrl+C to attempt to cancel the current operation
2. If unresponsive, you may need to close the terminal and restart

What's Wrong or Missing?

These pages explain what claude agents, claude logs <id>, and claude daemon status do, but they do not document the failure mode where claude agents or claude logs <id> cannot talk to the background supervisor.

That became a user-visible workflow change in v2.1.144: opening a session from claude agents or running claude logs <id> no longer hangs indefinitely when the background service is unresponsive, and now times out after 10 seconds with a recovery hint.

The docs still leave users with only generic "close the terminal and restart" advice, rather than background-session-specific recovery steps tied to the documented supervisor commands.

Suggested Improvement

Add a short troubleshooting subsection to agent-view for an unresponsive background service, and cross-link it from the CLI reference and troubleshooting page.

Suggested content:

If claude agents or claude logs <id> times out after about 10 seconds: the background supervisor may be unresponsive.

1. Run claude daemon status to check whether the supervisor is reachable.
2. Retry claude agents or claude logs <id> after the supervisor is healthy again.
3. If a specific background session still needs restarting, use claude respawn <id>.

This would turn the v2.1.144 recovery hint into durable documentation instead of leaving it only in the changelog and CLI output.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: This became a documented-user-facing behavior change in v2.1.144, where claude agents and claude logs <id> now time out after 10 seconds and show a recovery hint when the background service is unresponsive.