/hooks panel
Navigation, enablement, installation, defaults, Presets, and removal.
/hooks opens the session Hook Catalog panel only in Pi’s interactive TUI.
It shows Catalog Entries grouped by Source, their direct or Preset-derived
enablement, persisted default preference, and contextual actions for the
focused row. RPC receives one notification that TUI mode is required; JSON
and print modes return silently. No non-TUI invocation changes the Catalog or
session enablement. See Runtime modes.
Installation and new-Preset creation target project storage, so they require a trusted project and a valid Catalog. Other entry mutations write the authorized storage that owns the focused entry. HooKit neither reads nor writes untrusted project storage.
Navigation and search
| Input | Behavior |
|---|---|
| Up / Down | Moves focus through entries, crossing Section boundaries. Configured tui.select.up and tui.select.down bindings also apply. |
| Tab / Shift+Tab | Jumps to the next or previous Source Section. |
/ | Enters fuzzy search over name, description, Source, shell, when, Action detail, and Preset references. While a search filter is active, / resumes editing the retained query. |
| Backspace | Removes the last search character while editing a query. |
| Esc | Exits search and restores the normal view, whether query editing or filtered work mode is active. With no search active, closes /hooks. Configured tui.select.cancel also applies. |
| Enter | While query editing, locks the current filter into filtered work mode without changing enablement. Otherwise, toggles direct enablement for the focused entry. Configured tui.select.confirm also applies. |
Search ranks matches by field tier—name, description, Source, then body fields— and preserves Catalog order within a tier. Search changes only the visible subset; it does not create a second Catalog or renderer path.
Filtered work mode
Enter locks the current filter into filtered work mode: the retained query
stays applied (shown dim, without a cursor), the matching Catalog Entries stay
filtered, the focused row stays focused, and match highlighting persists.
Locking the search does not toggle the focused entry. In filtered work mode the
ordinary panel-wide action below (d) and focused-row actions (Enter, t,
r, e) are reachable again, so several matching entries can be changed
without retyping the query. Esc clears search and restores the full view; /
returns to editing the retained query.
Panel actions
These keys apply in the normal view. While editing a query, printable keys
become part of the query instead. a, i, n, and p stay inert whenever a
search filter is active (editing or filtered work mode) so an active result set
cannot be hidden, rebuilt, or jumped away from; d, t, r, and e remain
available in filtered work mode.
| Key | Action | Scope and constraints |
|---|---|---|
i | Install Hooks | Opens repository → file → entry selection. Enter installs a missing entry, updates an outdated entry, or asks before uninstalling an installed entry. |
n | New Preset | Creates a new empty local Preset, then opens its member editor. |
p | Presets | Jumps focus to the always-first Presets Section. |
d | Turn all off | Clears every directly enabled Catalog Entry. |
t | Toggle default | Changes the focused entry’s persisted default preference. |
r | Remove | Requests confirmation before removing the focused Catalog Entry from project storage. |
e | Edit Preset | Edits only a focused local Preset. Repository Presets are read-only. |
Enablement and defaults
Enter changes direct enablement for the current session branch. A Hook may
also be enabled indirectly through one or more directly enabled Presets; the
panel renders that state as enabled · via <preset>. Multiple paths never
execute one Hook twice in an Enabled Hook Set.
t changes the persisted default field, not current direct enablement. Current
defaults are used only when a session has no saved enablement set; a saved set,
including an empty one, overrides them. See Presets and sources
for restoration and expansion semantics.
Entry indicators
| Indicator | Meaning |
|---|---|
❄ | A repository Preset is read-only; only local Presets can be edited. |
§ | A Preset contains one or more unresolved Hook References. The available members still enable. |
⚠ | The installed entry is absent from its Source repository according to the latest successful lookup. r removes it. |
Network failure suppresses orphan detection rather than marking entries
incorrectly. The install picker separately identifies outdated entries by
comparing the repository file being browsed with installed content; local
default preferences are excluded from that comparison.