# GPU and terminal rendering Source: https://docs.ideharmony.com/troubleshooting/gpu-and-terminal-rendering ## First: is it the renderer or the process? The cheapest possible test, and it decides everything else: **Does it happen in one pane, or all of them?** | Answer | Cause | |---|---| | One pane | The process in that pane | | All panes | Rendering | A single process producing megabytes a second will look like a rendering failure. It is not — rendering is bounded, and that process will dominate whatever budget exists. --- ## Output tears or stutters **Likely causes** 1. GPU acceleration interacting badly with your driver. 2. A process writing faster than any renderer can keep up. **Repair for the second, which is more common than people expect:** redirect the noisy output to a file. ```powershell npm run build > build.log 2>&1 ``` You lose nothing — the log is more searchable than scrollback — and the terminal stops being the bottleneck. --- ## Text renders with wrong characters or broken boxes **Likely cause:** terminal capability. Unicode, colour depth, and box-drawing support vary widely between emulators. **Safe diagnostic:** try another terminal emulator. If it renders correctly there, it is capability, not Harmony. Harmony detects terminal capabilities and adapts, and carries an explicit registry of handled degradations. A reproducible rendering failure **in a common emulator** is worth reporting — include the emulator name and version, because that is the part that identifies it. --- ## The TUI redraws oddly or duplicates lines **Context:** the TUI renders diff-based frames — only changed lines redraw — and maintains a conversation projection that deduplicates prompt echoes and coalesces streaming and tool lifecycle events. **Likely causes** 1. The emulator mishandling cursor positioning. 2. A resize mid-render. **Repair:** resize the window, which forces a full redraw. If it persists across emulators, report it with the emulator name. --- ## Screenshots look blank but the screen looks fine **Likely cause:** GPU compositing — the surface renders in a layer the capture path does not see. This matters mainly when an agent is driving a browser surface and taking screenshots. **The agent may be receiving a blank image while you see content.** **Safe diagnostic:** capture the same surface twice and compare against what you see. > [!NOTE] > If an agent reports that a page is empty and you can see it is not, suspect > capture before concluding the agent is confused. --- ## Everything is slow rather than wrong That is not a rendering problem. See [performance problems](/docs/troubleshooting/performance), which separates the four different things that present as slowness. --- ## Reducing rendering load | Action | Effect | |---|---| | Fewer panes per workspace | Rendering and supervision stay predictable | | Redirect noisy output to files | Removes the dominant cost | | Lower density preset | Less to draw | | Reduced motion | Honoured throughout | A workspace caps at **20 panes**. Approaching that is a signal, not a target. --- ## Collecting evidence ```powershell harmony doctor --json ``` Include: emulator name and version, whether it reproduces in a second emulator, one pane or all, and GPU/driver if you have it. > [!WARNING] > Screenshots capture whatever is on screen — including paths, repository names, > and anything you echoed earlier. Check before sharing. ## Related - [Performance problems](/docs/troubleshooting/performance) - [Terminals](/docs/desktop/terminals) - [TUI problems](/docs/troubleshooting/tui)