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

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== Černé čtverečky v terminálu Claude Code ======

//Vytvořeno: **7.6.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://code.claude.com/docs/en/terminal-config|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.

===== TL;DR =====

  * 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.

===== Co se děje =====

Podle [[https://code.claude.com/docs/en/terminal-config|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.

===== Řešení 1: 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:

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

<code json>
{
  "terminal.integrated.gpuAcceleration": "off"
}
</code>

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

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

===== Proč /terminal-setup v tomto setupu nepomůže =====

''/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.

===== Řešení 2: tmux config =====

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:

<code bash>
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
</code>

Aplikace bez restartu tmuxu:

<code bash>
tmux source-file ~/.tmux.conf
</code>

===== Řešení 3: SSH a samostatný terminál =====

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 [[https://github.com/anthropics/claude-code/issues/24102|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.

===== Rychlá diagnostika =====

^ Kde se čtverečky objeví ^ Pravděpodobná příčina ^ Řešení ^
| Jen ve VS Code integrovaném terminálu | GPU akcelerace terminálu ve VS Code | Vypnout ''terminal.integrated.gpuAcceleration'' |
| I v čistém SSH terminálu mimo VS Code | Font nebo chybějící glyfy | Změnit font host terminálu nebo doinstalovat symbolový font |

===== Vybledlé barvy nejsou totéž =====

Při hledání lze narazit i na issue [[https://github.com/anthropics/claude-code/issues/46146|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:

<code bash>
export CLAUDE_CODE_TMUX_TRUECOLOR=1
</code>

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í.

===== Zdroje =====

  * [[https://code.claude.com/docs/en/terminal-config|Claude Code – Configure your terminal]]
  * [[https://github.com/anthropics/claude-code/issues/24102|anthropics/claude-code#24102 – Unicode glyfy / fonts-symbola]]
  * [[https://github.com/anthropics/claude-code/issues/46146|anthropics/claude-code#46146 – vybledlé barvy v tmuxu]]