Safe mode
Starting without optional extension code so you can remove whatever is breaking the app.
Safe mode starts Harmony without loading optional extension code. It exists for one situation: something you installed prevents the app from starting or working, and you need to get in to remove it.
IMPORTANT
Reach for safe mode before deleting configuration. Deleting your config takes your settings, profiles, layouts, and workspace definitions with it, and it usually was not the problem. Safe mode exists so that step is unnecessary.
When to use it
| Symptom | Safe mode helps? |
|---|---|
| App will not start after installing an extension | Yes |
| App starts, then becomes unresponsive | Yes |
| Everything slowed down after an install | Yes — isolates it |
| A skill will not load | Sometimes — confirms whether it is extension-related |
| Daemon unreachable | No — see daemon problems |
| Provider will not authenticate | No — see authentication |
Safe mode isolates extension code. It does not fix transport, credentials, or packaging problems, and using it for those wastes time.
What it does not disable
Safe mode is narrower than people expect:
| Still active | Why |
|---|---|
| The daemon | It is the product, not an extension |
| Your sessions, tasks, artifacts | Durable state is untouched |
| Your workspaces | Configuration is read, not executed |
| Provider CLIs you launch | Separate processes |
Safe mode is not a factory reset. Nothing is deleted. It changes what gets loaded at startup, and that is all.
The isolation loop
- Start in safe mode.
- Confirm the problem is gone. If it is not, the cause is not an extension — stop here and look elsewhere.
- Restart normally with one extension enabled.
- Repeat until the problem returns.
- The last one you enabled is the cause.
Reintroducing one at a time is slower and it is the only approach that identifies the culprit rather than making the symptom disappear for unclear reasons.
TIP
Note what you disabled as you go. Three restarts in, "which ones have I already ruled out" becomes a real question.
Once you have found it
- Remove it through the surface that installed it, not by hand-editing. Hand-removal leaves Harmony believing it is still registered.
- Verify with
nala doctor. - Report it if a single extension could crash the whole app — that is a
defect. Include the extension, its version, and redacted
nala doctor --json.
If safe mode does not help
The problem is not extension code. Work through, in order:
- Daemon problems — transport and instance isolation.
- Installation problems — a broken or partial install.
- Performance problems — load rather than failure.
nala doctor --json
WARNING
Review diagnostics before sharing. They contain absolute paths, workspace and repository names, and provider details.
Why this exists at all
Extension code is not sandboxed. It runs with the privileges of the process that loads it. A failing extension should degrade only its own feature, but "should" is not "will" — safe mode is the guaranteed way back in when it does not.
That is also the argument for installing deliberately in the first place. See customization.