Extension problems
An extension broke the app, a skill will not load, or something started behaving differently after you installed one.
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
nala 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
- It is scoped to a project you are not in.
- It failed its permission gate at load.
- Its source precedence is being overridden.
Safe diagnostic
/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 NALA, that is a defect worth reporting —
include the extension, the version, and nala 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.