Skip to content

v3.0.1 — "Clean Uninstall" (hotfix)

Choose a tag to compare

View all tags
@NickCirv NickCirv released this 24 Apr 16:53
v3.0.1
ac1160e

v3.0.1 — Clean Uninstall

Patch release. No feature changes. Fixes the orphaned-hooks bug @freenow82 reported within hours of 3.0.0 going live. Apologies to anyone who hit it.

What 3.0.0 shipped with

npm uninstall -g engramx removed the binary from PATH but left the hook entries in ~/.claude/settings.json pointing at a engram intercept command that no longer existed. Claude Code fires those hooks on every tool call — the commands failed with ENOENT — user-visible behaviour was "Claude Code stopped executing anything." Recovery required reinstalling engramx just to run engram uninstall-hook before uninstalling again. That is a bad experience.

What 3.0.1 does

  • scripts/preuninstall.mjs runs automatically on npm uninstall -g engramx. Strips every engram-tagged hook from ~/.claude/settings.json, drops the HUD statusLine, backs up the original to a timestamped .bak, writes atomically via rename. Hard contract: this script NEVER fails the uninstall. Every error path logs a one-line hint and exits 0. The user's npm uninstall always succeeds, with or without hook cleanup.
  • scripts/postinstall.mjs prints a one-time info banner on npm install -g engramx showing the next step (engram setup) and the clean-uninstall flow. Respects $CI and $ENGRAM_NO_POSTINSTALL=1.
  • New engram repair-hooks CLI alias — literally the same command as engram uninstall-hook, named so stranded users can find it by the word they'd actually search for.
  • README has a new "Want out?" section with the clean-uninstall command and a link to the recovery path for anyone stranded on 3.0.0.

If you installed 3.0.0 and your Claude Code is still broken

Two paths:

Fast, no reinstall (requires jq — brew install jq on mac, apt install jq on Linux):

jq 'walk(if type == "object" and .hooks? then
  .hooks |= map(select(.command // "" | test("engram"; "i") | not))
else . end)' ~/.claude/settings.json > /tmp/claude-settings.json && \
cp ~/.claude/settings.json ~/.claude/settings.json.bak && \
mv /tmp/claude-settings.json ~/.claude/settings.json

Works from 3.0.1:

npm install -g engramx@3.0.1
engram repair-hooks --scope user    # or: engram uninstall-hook --scope user
# Claude Code is clean. You can keep engramx, or:
npm uninstall -g engramx             # preuninstall will run this time

Verification

The preuninstall script was fixture-tested before shipping: a synthesized settings.json with a mix of engram hooks, unrelated custom hooks in the same event arrays, an engram statusLine, and unrelated top-level keys. Post-run:

  • ✅ 3 engram hook entries removed
  • ✅ custom echo 'my custom hook' preserved in PreToolUse
  • ✅ custom SessionStart hook preserved
  • ✅ unrelated Stop hook (no engram reference) completely untouched
  • ✅ engram statusLine removed
  • ✅ unrelated top-level otherUserPrefs preserved byte-for-byte
  • ✅ timestamped .bak file created
  • ✅ no engram substring anywhere in the result

CI also green — Ubuntu + Windows × Node 20 + 22, all 878 tests passing.

Thanks

@freenow82 — this is the report that turns a launch into a better tool. Genuinely grateful.

Assets 2
Loading