claude-code - 💡(How to fix) Fix [DOCS] `/tui` docs omit that running background shells and subagents block renderer switching [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/fullscreen

Section/Topic

The "Enable fullscreen rendering" section and the /tui command documentation

Current Documentation

The /tui docs currently say:

Run /tui fullscreen inside any Claude Code conversation. The CLI saves the tui setting and relaunches into fullscreen with your conversation intact, so you can switch mid-session without losing context. Run /tui with no argument to print which renderer is active.

And the command reference says:

/tui [default\|fullscreen] | Set the terminal UI renderer and relaunch into it with your conversation intact. fullscreen enables the flicker-free alt-screen renderer. With no argument, prints the active renderer

What's Wrong or Missing?

These pages do not document the v2.1.141 behavior change for /tui: if the current session still has running background shells, workflows, or subagents, Claude Code now refuses to relaunch and tells the user to wait for those tasks to finish instead of silently dropping them.

As written, "with your conversation intact" overstates what users can expect during a renderer switch and gives no guidance for the refusal path. That is especially confusing because similar safety behavior is documented elsewhere for backgrounding, but not on the /tui pages themselves.

Suggested Improvement

Add a short note to the /tui command docs and the fullscreen page clarifying that renderer switching is blocked while the current session has active background work.

Suggested wording:

If the current session has running background tasks such as background shells, workflows, or subagents, /tui refuses to relaunch so those tasks are not dropped. Wait for them to finish, or inspect them with /tasks, then run /tui again.

This note should apply to both /tui fullscreen and /tui default.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Cross-reference:

Version context: v2.1.141 changelog entry: "Fixed /tui silently dropping running background shells and subagents — now refuses and asks to wait for them to finish"