GPU and terminal rendering
Output tears, stutters, renders wrong, or disappears — separating the process from the renderer.
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
- GPU acceleration interacting badly with your driver.
- 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.
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
- The emulator mishandling cursor positioning.
- 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, 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
nala 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.