claude-code - 💡(How to fix) Fix [DOCS] Agent view pinning docs omit pinned background session lifecycle behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Pinning sessions with Ctrl+T and the "How background sessions are hosted" lifecycle details

Current Documentation

The agent view page currently says:

Run claude agents to open agent view. It takes over the full terminal and lists every session grouped by state, with pinned sessions and the ones that need you at the top.

Within a group:

• Press Ctrl+T to pin a session to the top

Later, the same page says:

Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running.

Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off.

The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular auto-updater replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them.

What's Wrong or Missing?

Changelog v2.1.147 says:

Pinned background sessions (Ctrl+T in claude agents) now stay alive when idle, are restarted in place to apply Claude Code updates, and are shed under memory pressure only after non-pinned sessions

A. Pinning is documented as list ordering only

The current agent-view page says Ctrl+T pins a session to the top, but it does not explain that pinning now changes session lifecycle behavior.

B. The lifecycle section still reads like all finished idle sessions are treated the same

The page says an unattached finished session is stopped after about an hour to free resources, with no exception for pinned sessions that now stay alive when idle.

C. The new update and memory-pressure behavior is undocumented

There is no documentation that pinned sessions are restarted in place to apply Claude Code updates, or that memory-pressure shedding now prefers non-pinned sessions first.

Suggested Improvement

Update agent-view to document what pinning does beyond row ordering:

1. In the pinning shortcut/list-organization section, explain that pinned background sessions are kept alive while idle.
2. In the supervisor lifecycle section, document that pinned sessions are restarted in place when Claude Code updates are applied.
3. Document the memory-pressure policy explicitly: non-pinned sessions are shed before pinned ones.
4. Clarify any remaining limits, such as machine shutdown still stopping local background sessions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Relevant release note: changelog v2.1.147 adds the pinned background-session behavior, but the agent-view reference page does not yet describe it.