# Extension problems Source: https://docs.ideharmony.com/troubleshooting/extensions Extensions run with real privileges and are **not sandboxed**. That makes them the first thing to suspect when behaviour changes for no other reason. --- ## The app will not start after installing something **Likely cause:** an extension failing during load. **Repair:** start in **safe mode**, which loads without optional extension code, then remove the offender. **When not to retry:** do not delete your whole configuration to get back in. Safe mode exists precisely so you do not have to, and a deleted config takes your settings, profiles, and layouts with it. --- ## Something behaves differently and I did not change a setting **Likely cause:** a hook. Hooks fire on events rather than on your command, so their effects appear without an obvious trigger. **Safe diagnostic** ```powershell harmony doctor ``` Also check **Settings → Claude Code** for an installed hook bridge, and its status. > [!IMPORTANT] > A hook you installed once runs on every matching event from then on. Unlike a > command you type or a skill an agent invokes, its execution is not a decision > you make each time. When behaviour changes mysteriously, hooks are the right > first suspicion. --- ## A skill does not appear or will not run **Likely causes** 1. It is scoped to a project you are not in. 2. It failed its permission gate at load. 3. Its source precedence is being overridden. **Safe diagnostic** ```text /skills ``` **Expected evidence:** whether the skill is known but unavailable, or not known at all. Those are different problems — the first is scope or permission, the second is installation. --- ## Everything slowed down after installing an extension **Cause:** an extension doing work on every event. **Safe diagnostic:** start in safe mode. If responsiveness returns, reintroduce extensions one at a time rather than all at once. Hook signals are rate-limited, so a chatty hook is metered rather than allowed to saturate the workspace — but metered still costs something. > [!NOTE] > The failure mode of a noisy extension is not an error message. It is > everything else becoming slow, which is why it goes undiagnosed for so long. --- ## A project configuration is not being applied **Likely cause:** trust. Project config — `nala.json`, or legacy `wmux.json` — is trust-gated per project root. **This is intended.** The file is content written by whoever wrote the repository, and opening a folder must not be enough to let it start processes. **Repair:** grant trust deliberately, after reading what the file declares. > [!SECURITY] > Read a project config before trusting it, particularly in a repository you did > not write. It can declare startup processes. --- ## An extension crashed the whole application A failing extension should degrade its own feature, not take the app down. **If a single extension can crash Harmony, that is a defect worth reporting** — include the extension, the version, and `harmony doctor --json`. --- ## Before installing anything Extension code is not sandboxed. It runs with the privileges of the process that loads it, with your credentials in scope. | Ask | Because | |---|---| | Do I trust the author? | There is no containment to fall back on | | Does it need a hook, or would a command do? | Hooks run without you deciding each time | | Can I read the source? | "It's popular" is not a security property | Treat it exactly as seriously as `npm install` of an unfamiliar package. ## Related - [Customization overview](/docs/customization) - [Hooks](/docs/customization/hooks) - [Security overview](/docs/security)