Skip to content

docs(hooks): clarify plugin auto-installs hooks; update manual install to use CLI - #1187

Closed
ichoosetoaccept wants to merge 1 commit into
MemPalace:developfrom
detailobsessed:docs/fix-hooks-install-instructions
Closed

docs(hooks): clarify plugin auto-installs hooks; update manual install to use CLI#1187
ichoosetoaccept wants to merge 1 commit into
MemPalace:developfrom
detailobsessed:docs/fix-hooks-install-instructions

Conversation

@ichoosetoaccept

Copy link
Copy Markdown

What does this PR do?

The hooks guide told all users to manually add hooks to settings.json using absolute bash script paths. This is wrong in two ways:

  1. Plugin users don't need to do anything — hooks are registered automatically by the Claude Code plugin runtime (loaded in-memory from hooks/hooks.json at session start). Adding manual entries on top causes both Stop and PreCompact hooks to fire twice per event.

  2. Non-plugin users (pip/uv standalone installs) should use mempalace hook run CLI, not absolute paths to internal bash wrapper scripts.

Changes:

  • Add Via Plugin (Recommended) section — hooks are automatic, with a double-registration warning
  • Rename old section to Without Plugin (Manual) and update commands to mempalace hook run --hook stop --harness claude-code
  • Update Codex section to use mempalace hook run --hook stop --harness codex
  • Remove matcher from Stop/PreCompact examples (matchers are for tool-name filtering in PreToolUse/PostToolUse, not event-based hooks)
  • Remove instruction to edit bash scripts directly from Configuration section

Related to #408 — the old manual workaround existed partly because earlier versions used python3 -m mempalace which silently failed on uv installs. With 3.3.3 using mempalace hook run, plugin-managed hooks work correctly.

How to test

Install via Claude Code plugin marketplace, run /hooks — both Stop and PreCompact appear automatically, sourced from ~/.claude/plugins/*/hooks/hooks.json. Nothing in settings.json. Check ~/.mempalace/hook_state/hook.log to confirm saves fire.

Checklist

  • Tests pass (python -m pytest tests/ -v)
  • No hardcoded paths
  • Linter passes (ruff check .)

@ichoosetoaccept
ichoosetoaccept force-pushed the docs/fix-hooks-install-instructions branch from 9adea4d to 5a41960 Compare May 2, 2026 10:55
@igorls igorls added area/cli CLI commands area/hooks Claude Code hook scripts (Stop, PreCompact, SessionStart) area/install pip/uv/pipx/plugin install and packaging documentation Improvements or additions to documentation labels May 2, 2026
@milla-jovovich

Copy link
Copy Markdown
Collaborator

Thanks for catching the double-firing — clean fix.✨

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/cli CLI commands area/hooks Claude Code hook scripts (Stop, PreCompact, SessionStart) area/install pip/uv/pipx/plugin install and packaging documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants