Hooks
Lifecycle handlers that fire automatically, and why that makes them the highest-risk extension point.
A hook runs on an event rather than on your command. That is what makes them useful, and it is exactly what makes them the extension point to be most careful with.
SECURITY
A hook you install today runs on every matching event from then on, without asking. Unlike a skill an agent chooses to invoke, or a command you type, a hook's execution is not a decision you make each time. Install accordingly.
The Claude Code hook bridge
The most exercised integration. Harmony can install a bridge so Claude Code lifecycle signals reach Harmony — surfacing agent activity in the workspace rather than only inside that CLI's own output.
Manage it under Settings → Claude Code: install, remove, and check status.
NOTE
The settings tab warns about plugin conflicts. If you already have hooks configured for that provider, read the warning rather than clicking through — two systems writing the same hook configuration is a genuinely confusing failure to debug later.
Flood protection
Hook signals are rate-limited. A misbehaving hook that fires continuously is metered rather than allowed to saturate the workspace, and signal latency is measured.
This matters because the failure mode of a chatty hook is not an error message — it is everything else becoming slow. Bounding it turns an invisible degradation into a visible one.
Registration is surgical
Harmony's integration writes only what it needs and preserves the rest of your configuration. It does not rewrite a provider's config wholesale.
Verify what was registered:
nala doctor
The General settings tab also shows the config path and its modified time per target, so you can confirm what changed and when.
Writing your own
Before writing a hook, check whether a command or skill would do. Ordered by how much you keep control:
| Mechanism | Runs when | You decide each time? |
|---|---|---|
| Command | You type it | Yes |
| Skill | An agent invokes it | Agent decides, gated by permissions |
| Hook | An event fires | No |
A hook is the right answer when the behaviour genuinely must be automatic — reacting to a session lifecycle event, for instance. It is the wrong answer when you simply want something convenient to run.
Failure isolation
A failing hook should degrade its own behaviour rather than take the application down. If a single hook can crash the app, that is a defect worth reporting, not expected behaviour.
Removing a hook
Remove through the same surface that installed it, then verify:
nala doctor
Hand-editing a provider's configuration to remove a Harmony-installed hook leaves Harmony believing it is still registered. Use the toggle.