Černé čtverečky v terminálu Claude Code

Vytvořeno: 7.6.2026 | Aktualizováno: 07.06.2026 20:26

Claude Code je AI coding assistant od Anthropicu pro příkazovou řádku. Tento zápis řeší problém s černými čtverečky nebo zkomoleným textem v terminálu při běhu Claude Code v kombinaci Docker, Alpine Linux, ARM64, tmux a VS Code integrovaný terminál.

• Hlavní příčina ve VS Code: GPU akcelerace vykreslování integrovaného terminálu může způsobit černé čtverečky nebo garbled text.
• Ověřený fix: v lokálním VS Code nastavit terminal.integrated.gpuAcceleration na off a reloadnout okno.
• Příkaz /terminal-setup v tomto setupu nemusí pomoct, protože běží uvnitř tmuxu a Dockeru, takže nedosáhne na konfiguraci host terminálu nebo lokálního VS Code.
• Pokud se čtverečky objevují i přes běžný SSH terminál mimo VS Code, může jít o chybějící glyfy fontu na straně host terminálu.

Podle oficiální dokumentace Claude Code ke konfiguraci terminálu nastavuje /terminal-setup ve VS Code, Cursoru nebo Devin Desktopu hodnotu terminal.integrated.gpuAcceleration na off, aby zabránil zkomolenému textu v integrovaném terminálu.

V tomto konkrétním setupu šlo o Claude Code běžící v Linuxu uvnitř Dockeru, v Alpine Linuxu na ARM64 a zároveň v tmuxu. Původně to vypadalo jako problém Claude Code nebo tmuxu, ale prakticky pomohla změna nastavení lokálního VS Code.

Nastavení patří do lokálního VS Code na vlastním stroji, ne do kontejneru. Terminál totiž vykresluje okno VS Code lokálně.

Postup:

1. Ve VS Code otevřít paletu příkazů: Ctrl/Cmd + Shift + P.
2. Spustit Preferences: Open User Settings (JSON).
3. Přidat nastavení:

{
  "terminal.integrated.gpuAcceleration": "off"
}

1. Reloadnout okno přes Ctrl/Cmd + Shift + P → Developer: Reload Window.

Vrácení zpět: nastavit hodnotu na auto a znovu reloadnout okno.

/terminal-setup je užitečný příkaz, ale musí běžet tam, kde má přístup ke konfiguraci terminálu. V tomto setupu tomu brání dvě věci:

• tmux – dokumentace doporučuje spustit /terminal-setup přímo v host terminálu, ne uvnitř tmuxu nebo screenu, protože potřebuje zapsat konfiguraci host terminálu.
• Docker – Claude Code běží uvnitř kontejneru, ale settings.json lokálního VS Code je na hostiteli. Z kontejneru se k němu Claude Code běžně nedostane.

Proto bylo potřeba nastavit terminal.integrated.gpuAcceleration ručně ve VS Code.

Tmux nemusí být hlavní příčina černých čtverečků, ale pro Claude Code se hodí doplnit konfiguraci, která řeší passthrough, rozšířené klávesy a truecolor.

Do ~/.tmux.conf v kontejneru:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Aplikace bez restartu tmuxu:

tmux source-file ~/.tmux.conf

Pokud se čtverečky objeví i při připojení klasickým terminálem přes SSH mimo VS Code, může jít o chybějící glyfy fontu. Font pak nezvládá vykreslit některé Unicode symboly, které Claude Code používá, a místo nich zobrazí čtverečky nebo náhradní symboly.

Související je issue anthropics/claude-code#24102 – Unicode symbols render as hex codepoints on Linux without fonts-symbola.

Řešení je na straně host terminálu, ne uvnitř kontejneru:

• použít font s dobrým pokrytím symbolů a emoji, například JetBrains Mono, Iosevka, DejaVu Sans Mono nebo Nerd Font variantu,
• na Linux hostu doinstalovat symbolový font, například fonts-symbola nebo ekvivalent.

Důležité je, že v Alpine Linuxu uvnitř Dockeru glyfy vykresluje vnější terminál: okno VS Code nebo SSH klient. Font se proto řeší tam, ne uvnitř Alpine kontejneru.

Při hledání lze narazit i na issue anthropics/claude-code#46146 – vybledlé barvy v tmuxu. To ale není problém černých čtverečků. Týká se vybledlých barev v tmuxu, kdy může dojít k omezení barev při detekci proměnné $TMUX.

Pokud by vedle čtverečků vypadaly barvy vybledle, dá se zvlášť vyzkoušet:

export CLAUDE_CODE_TMUX_TRUECOLOR=1

K tomu je potřeba mít správně nastavený truecolor passthrough v tmuxu. Se samotnými černými čtverečky to ale přímo nesouvisí.

• Claude Code – Configure your terminal
• anthropics/claude-code#24102 – Unicode glyfy / fonts-symbola
• anthropics/claude-code#46146 – vybledlé barvy v tmuxu