[BUG] Excessive blank lines when rendering nested markdown structures in terminal

[BUG] Excessive blank lines when rendering nested markdown structures in terminal

Description

Claude Code terminal output contains excessive blank lines (~27 consecutive blank lines) when rendering responses with nested markdown structures (headings + subheadings + multiple bullet lists). This makes the terminal output difficult to read and wastes significant screen space.

Environment

• Claude Code Version: v2.0.73
• Model: Claude Sonnet 4.5
• Platform: Windows (via SSH to Linux/tmux)
• Terminal: tmux on Linux (Ubuntu 25.10)
• Date: 2025-12-19

Steps to Reproduce

1. Ask Claude to provide a structured summary with:

• Main heading (## Heading)
• Multiple subheadings (### Subheading)
• Nested bullet lists under each subheading
• Multiple sections (e.g., 5+ subsections)

1. Example prompt that triggers the issue:

``
"List all the missing files I need to copy, organized by category"
``

1. Claude responds with structure like:

```markdown
## Missing Files Copied

### Main Package (2 files):

• file1.pgs
• file2.pgb

### Constants Packages (24 files):
CH (Switzerland):

• file_ch_opel.pgs/pgb
• file_ch_peugeot.pgs/pgb

CZ (Czech Republic):

• file_cz_opel.pgs/pgb

(... more sections ...)
```

1. Observe the terminal output

Expected Behavior

The markdown structure should render with reasonable vertical spacing:

• 1-2 blank lines between sections
• Bullet lists should be compact
• Total vertical space: ~30-40 lines for a moderate summary

Actual Behavior

The markdown structure renders with excessive blank lines:

• ~27 consecutive blank lines appear in the middle of the response
• Content appears to be missing (but is actually just rendered as whitespace)
• Total vertical space: 80+ lines for the same content
• Makes terminal output extremely difficult to read

Evidence

Terminal capture showing the issue:

Line 88-114: 27 consecutive blank lines
Line 115: Text continues "...s have been copied to: C:\Users\..."

The entire structured list section (headings + bullet lists) was rendered as blank vertical space.

Impact

• Severity: Medium
• User Experience: Poor - makes terminal output hard to read
• Workaround Available: Yes - use simpler formatting (single-level lists, plain text)

Analysis

Potential Root Cause

This appears to be related to issue #1220 (missing line breaks in lists) which was fixed on November 30, 2025. The fix may have overcorrected, causing:

1. Before fix: Lists rendered on single line (missing line breaks)
2. After fix: Nested markdown structures render with excessive blank lines

The terminal renderer may be incorrectly calculating vertical space requirements for:

• Nested heading levels (##, ###)
• Multiple subheadings in sequence
• Bullet lists grouped under subheadings

Related Issues

• #1220 - List output missing line breaks (FIXED - may have introduced this issue)
• #11888 - Line breaks not rendering correctly (duplicate of #1220)
• #7670 - Unexpected line breaks in terminal output
• #10472 - Excessive blank lines causing scrolling (different root cause - ANSI escapes)

Suggested Fix

The terminal markdown renderer should:

1. Limit vertical spacing between heading levels (max 1-2 blank lines)
2. Collapse consecutive blank lines to max 2 lines
3. Treat nested bullet lists as compact structures
4. Add unit tests for rendering nested markdown structures

Reproduction Context

This occurred during a file copy operation where Claude provided a detailed summary of 26 files organized by category (Main Package, Constants for CH/CZ/SK/HR/SI). The structured response was appropriate, but the terminal rendering created excessive whitespace.

Workarounds

For users experiencing this issue:

1. Ask Claude to use simpler formatting (single-level lists)
2. Avoid nested markdown structures (no subheadings)
3. Request plain text summaries instead of markdown

For Claude:

1. Detect terminal output mode and use simpler formatting
2. Avoid combining multiple heading levels with bullet lists
3. Flatten hierarchical responses for terminal display

---

Additional Notes:

This issue specifically affects nested markdown structures. Simple lists (without headings/subheadings) render correctly. The problem appears to be in how the terminal renderer calculates vertical space for complex markdown hierarchies.

Feedback ID: (to be added after submission)