Performance problems
The app feels slow, the daemon is busy, or rendering stutters.
First, separate the four things that can be slow
They have different causes and different fixes:
| Slow thing | Usually |
|---|---|
| Terminal rendering | GPU or terminal capability |
| The UI itself | Too many panes, or an extension |
| The daemon | Sessions still live that you thought were closed |
| The agent | The provider, not Harmony |
Deciding which one you have first saves most of the time.
Terminal output stutters or tears
Likely causes
- GPU acceleration behaving badly with your driver.
- A process producing enormous output faster than it can be rendered.
Safe diagnostic: does it happen in one pane or all of them? One pane points at the process; all panes point at rendering.
Repair: for a single noisy process, redirect its output to a file rather than the terminal. Rendering is bounded, but a process writing megabytes a second will still dominate it.
The window feels sluggish
Likely causes
- Approaching the 20-pane-per-workspace cap.
- An extension doing work on every event.
Safe diagnostic: try a fresh workspace with two panes. If that is responsive, the problem is load or an extension rather than the app.
Repair: split work across workspaces rather than accumulating panes in one. The cap exists because past it, rendering and process supervision stop being predictable — treat approaching it as a signal, not a target.
For extensions, start in safe mode and reintroduce them one at a time.
The daemon is using resources with nothing running
Symptom: sustained CPU or memory with no visible activity.
Safe diagnostic
nala sessions list
nala tasks list
Expected evidence: sessions the daemon still considers live.
Repair: stop sessions you no longer need.
IMPORTANT
A pane that looks closed in the UI may still have a live process behind it, and an agent can hold a session open indefinitely while advancing nothing. Liveness is not progress — read task state.
When not to retry: do not delete the data directory to reclaim resources. It holds your durable sessions, tasks, and artifacts. It is not a cache.
An agent is slow
This is usually not Harmony. A turn's duration is dominated by the provider: the model, the effort setting, and that provider's current load.
Safe diagnostic: run the same provider directly, outside Harmony, with a comparable prompt.
Expected evidence: comparable slowness standalone means the provider.
Repair: choose a different model or effort setting. See providers, models, and routes.
NOTE
Check the route before concluding a model got worse. Route can change during a session or between plan steps, so two turns in one transcript are not necessarily comparable.
Work seems stalled but nothing is failing
Check delivery state rather than guessing. Five of the six states mean work has
not begun, and one of them — needs_enter — looks exactly like a working agent
from the outside.
See delivery lifecycle.
Collecting evidence
nala doctor --json
WARNING
Review before sharing: diagnostics contain absolute paths, workspace and repository names, and provider details.