[DOCS] [Fullscreen] Fullscreen docs omit `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` troubleshooting for Windows Terminal nested-subagent corruption

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The Research preview section and any troubleshooting guidance for fullscreen rendering problems, especially on Windows Terminal when nested subagents are updating the UI heavily.

Current Documentation

The fullscreen page currently says:

Fullscreen rendering is a research preview feature. It has been tested on common terminal emulators, but you may encounter rendering issues on less common terminals or unusual configurations. If you encounter a problem, run /feedback inside Claude Code to report it, or open an issue on the claude-code GitHub repo. Include your terminal emulator name and version. To turn fullscreen rendering off, run /tui default, or unset CLAUDE_CODE_NO_FLICKER if you enabled it that way. To force the classic renderer regardless of the saved tui setting, set CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1.

The nested-subagent docs currently say:

As of Claude Code v2.1.172, a subagent can spawn its own subagents. Use this when a delegated task itself splits into parallel subtasks, such as a reviewer subagent that dispatches a verifier per finding, so the intermediate output never reaches your main conversation.

The environment variable reference currently says:

CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT | Set to 1 to repaint the entire screen on every frame in fullscreen rendering instead of sending incremental updates. Use this if fullscreen mode shows stale or misplaced text fragments. Claude Code enables this automatically for background sessions and agent view on Windows

The troubleshooting page currently only offers this renderer-corruption guidance:

If characters render as boxes, smears, or the wrong glyphs when running Claude Code in the VS Code, Cursor, or Devin Desktop integrated terminal, the terminal's GPU renderer is likely the cause.

What's Wrong or Missing?

Claude Code v2.1.183 changelog adds this fix:

Fixed fullscreen TUI corruption (statusline mid-screen, duplicated spinner rows, merged text) in Windows Terminal under heavy nested-subagent load

The user-facing docs are still incomplete for that changed surface:

A. The fullscreen page does not surface the existing full-repaint workaround

fullscreen.md tells users to report the problem or disable fullscreen entirely, but it does not mention the already-documented CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT override for stale or misplaced fragments. That means the page most users will open for fullscreen rendering issues does not point to the relevant mitigation.

B. The nested-subagent docs do not warn or cross-reference the fullscreen troubleshooting path

sub-agents.md documents nested subagents as a supported workflow, but it does not mention that heavy nested-subagent activity was a Windows Terminal renderer edge case or point users to the fullscreen rendering workaround if they see corruption on older builds.

C. The troubleshooting page does not cover Windows Terminal fullscreen corruption

troubleshooting.md only discusses garbled text in editor-integrated terminals. A Windows Terminal user who sees a status line in the middle of the screen, duplicated spinner rows, or merged text has no troubleshooting entry that points to the documented repaint override or tells them this specific nested-subagent corruption was fixed in v2.1.183.

Suggested Improvement

Add a short fullscreen-rendering troubleshooting note, for example:

If fullscreen rendering shows stale or misplaced fragments, such as a status line in the middle of the screen, duplicated spinner rows, or merged text, set CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1 to force full-frame repaints instead of incremental updates. On Windows, Claude Code already enables this automatically for background sessions and agent view. If you hit this specifically in Windows Terminal while nested subagents are updating the screen heavily, upgrade to Claude Code v2.1.183 or later.

Then add:

1. A one-sentence cross-reference from sub-agents.md ("Spawn nested subagents") to the fullscreen troubleshooting note.
2. A troubleshooting entry for Windows Terminal fullscreen corruption that points to the same env var and mentions CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 as the fallback if a user needs to leave fullscreen entirely.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/fullscreen | 183-191 | Research preview tells users to report problems or disable fullscreen, but does not mention the existing full-repaint override |
| https://code.claude.com/docs/en/sub-agents | 784-790 | Nested subagents are documented as supported, with no Windows Terminal/fullscreen troubleshooting link |
| https://code.claude.com/docs/en/troubleshooting | 61-63 | Garbled-text troubleshooting only covers editor integrated terminals |
| https://code.claude.com/docs/en/env-vars | 148 | CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT already describes the correct mitigation, but it is buried in the env-var table instead of the fullscreen troubleshooting flow |

Total scope: 4 pages touched (fullscreen, sub-agents, troubleshooting, and an env-vars cross-reference).

Version: Claude Code v2.1.183 changelog says: "Fixed fullscreen TUI corruption (statusline mid-screen, duplicated spinner rows, merged text) in Windows Terminal under heavy nested-subagent load".