Dim/secondary text unreadable on light terminal themes (uses ANSI bright-black which is near-background on most light palettes)

Summary

Claude Code renders dim/secondary text (tool-result previews, "\… +N lines (ctrl+o to expand)" stage summaries, timestamps like "Cooked for 39s", diff context lines, thinking indicators) using the ANSI bright-black colour slot (palette index 8). Dark themes typically map this to a mid-grey that reads fine on a near-black background, but **most light themes map bright-black to a pale grey so it contrasts with their near-white background** — when that pale grey is placed on a light background, it becomes almost invisible.

The result: Claude Code is essentially unusable on light terminal themes without manual palette overrides.

Reproduce

1. Set your terminal to any popular light theme:

• GitHub Light Default
• Catppuccin Latte
• Tokyo Night Day
• GitHub Light High Contrast
• Gruvbox Light Hard

1. Run claude and interact normally.
2. Look at:

• Stage collapse summaries (\… +15 lines (ctrl+o to expand)\)
• "Cooked for Xs" / "Churned for Xs" timestamps
• Diff unchanged-context lines inside Update/Edit tool output
• The "Thinking…" indicator

Every one of these appears as ghosted, barely-visible text.

Why — root cause

Claude Code picks the ANSI bright-black slot for dim text. The 4-bit ANSI palette doesn't have a semantic "dim / disabled" slot — bright-black is traditionally used for dim on dark but is theme-defined, not a guaranteed-contrasted-against-background colour.

Representative bright-black values on popular light themes:
| Theme | Background | Bright-black | Contrast ratio vs bg |
|-------|------------|--------------|----------------------|
| GitHub Light Default | #ffffff | #8c959f | ~2.9:1 (below WCAG AA) |
| Catppuccin Latte | #eff1f5 | #acb0be | ~2.1:1 (fails AA) |
| Tokyo Night Day | #e1e2e7 | #a8aecb | ~2.0:1 (fails AA) |
| Gruvbox Light Hard | #f9f5d7 | #928374 | ~3.5:1 (below AA for body text) |

By contrast, dark themes land in the 5–8:1 range because their bright-black is much further from their background.

Suggested fixes (any one would resolve)

1. Render dim text using the terminal's actual foreground colour with a reduced opacity / ANSI "faint" (SGR 2) attribute, not bright-black. This lets the terminal decide legibility. True-colour terminals (Ghostty, WezTerm, Kitty, Alacritty) all support SGR 2.
2. Detect light vs. dark background at startup (many terminals expose this via OSC 11 query or via COLORFGBG) and choose either bright-black (dark bg) or plain black (light bg). Also reachable via os.environ['COLORFGBG'] or a tput colors-style check.
3. Expose a config option (dimTextColor or similar) so users can override the slot Claude Code uses for secondary text — pragmatic opt-in fix while the above are being designed.
4. Document the workaround in troubleshooting: override palette slot 8 in terminal config. E.g. for Ghostty: palette = 8=#4a4a4a. But this really should be shipped-sane rather than a workaround.

Workaround today

In Ghostty:

palette = 8=#4a4a4a

(And equivalent in other terminals.) This fixes dim text but also changes any program that uses bright-black, which isn't always desired.

Environment

• Claude Code 2.1.112
• Ghostty 1.2.3 (GTK single-instance, Wayland)
• KDE Plasma 6.4.5, Breeze Light global theme
• Tested themes: GitHub Light Default, Catppuccin Latte, TokyoNight Day, GitHub Light High Contrast, Gruvbox Light Hard — all exhibit the same unreadable-dim-text problem.