TUI misalignment caused by string-width miscalculating emoji character width on macOS 12

Resolved 💬 4 comments Opened Mar 3, 2026 by XuanLee-HEALER Closed Apr 1, 2026

Bug

Claude Code's TUI output is misaligned on macOS 12. Two symptoms:

  1. Main output: The bullet emoji (U+23FA) before each task item causes all subsequent text on the same line to be offset
  2. Status line: Emoji characters in the status bar render as garbled/misaligned text

Root cause: the internal string-width treats as 1 cell wide, but the terminal actually renders it as 2 cells wide.

Environment

  • macOS 12.7.6 (Monterey)
  • iTerm2 3.6.8
  • Claude Code 2.1.63
  • System ICU: 70.1 (libicucore.A.dylib)
  • Terminal: xterm-256color, locale en_US.UTF-8

Root Cause Analysis

  • Claude Code (Bun binary) links against /usr/lib/libicucore.A.dylib (ICU 70 on macOS 12)
  • System wcwidth(0x23FA) returns 1, but iTerm2 renders as 2 cells wide
  • The ambiguousIsNarrow option in string-width is likely defaulting to true, causing the mismatch
  • Does not reproduce on newer macOS versions (13+) with ICU 72+

Suggested Fix

  1. Pass { ambiguousIsNarrow: false } to string-width, or auto-detect based on terminal/OS environment
  2. Alternatively, provide a --no-emoji or --ascii flag to replace emoji indicators with plain ASCII characters

Reproduction

echo "X⏺X"
echo "XXX"
# Second X in first line is offset from third X in second line

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗