From f6946d72f47a0d33029551d68f8b47e96168c28e Mon Sep 17 00:00:00 2001
From: nntrivi2001 <vinnt@smartgift.vn>
Date: Mon, 10 Aug 2026 16:56:40 +0700
Subject: [PATCH] docs(plugins): fix inaccurate uninstall cleanup instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified against a real claude plugin uninstall: it only drops the plugin
from the enabled list. The server keeps running, the cached source stays on
disk, and the hook entries claude plugin install wrote into settings.json
are left behind pointing at the now-uninstalled cache dir — silently fails
once Claude Code eventually GCs it. The previous instructions ("uninstall
removes the hooks and the cached source") were untested assumptions; this
adds the missing settings.json cleanup step.
---
 docs/PLUGINS.md | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md
index 5b5e26c..c89de70 100644
--- a/docs/PLUGINS.md
+++ b/docs/PLUGINS.md
@@ -147,18 +147,47 @@ single port.
 
 ### Uninstalling
 
-`claude plugin uninstall ccam@claude-code-agent-monitor-plugins` removes the hooks
-and the cached source. It does not touch the state the plugin created outside
-the cache — remove those by hand if you want a clean machine:
+`claude plugin uninstall ccam@claude-code-agent-monitor-plugins` only removes
+the plugin from the enabled list — verified against a real install/uninstall,
+not assumed. It does **not**:
+
+- stop the running server (it keeps serving from the now-uninstalled cache dir)
+- remove the cached source under `~/.claude/plugins/cache/.../ccam/<version>/`
+- remove the hook entries `claude plugin install` wrote into
+  `~/.claude/settings.json` (still pointing at that cache dir — they keep
+  firing, and keep working, until the cache directory is eventually GC'd by
+  Claude Code, at which point they silently start failing)
+- remove `~/.local/bin/ccam` or `~/.claude/agent-dashboard/runtime/`
+
+For a clean machine, do all of this yourself:
 
 ```bash
-kill "$(node -e 'console.log(JSON.parse(require("fs").readFileSync(require("os").homedir()+"/.claude/.agent-dashboard.json","utf8")).servers[0].pid)')"
+# 1. Stop the server (skip if ~/.claude/.agent-dashboard.json is already gone)
+kill "$(node -e 'console.log(JSON.parse(require("fs").readFileSync(require("os").homedir()+"/.claude/.agent-dashboard.json","utf8")).pid)')"
+
+# 2. Runtime state and the CLI launcher
 rm -rf ~/.claude/agent-dashboard/runtime    # deps, UI bundle, logs, state
-rm -f ~/.local/bin/ccam                     # the CLI launcher
-# ~/.claude/agent-dashboard/ still holds the database — delete it only if you
-# want the recorded history gone too.
+rm -f ~/.local/bin/ccam
+
+# 3. The hook entries claude plugin install wrote (settings.json is not
+#    ours to fully own — back it up first and only drop entries mentioning
+#    hook-handler.js)
+node -e '
+const fs = require("fs");
+const p = require("os").homedir() + "/.claude/settings.json";
+const d = JSON.parse(fs.readFileSync(p, "utf8"));
+fs.copyFileSync(p, p + ".ccam-bak2");
+for (const [type, entries] of Object.entries(d.hooks || {})) {
+  const kept = entries.filter((e) => !JSON.stringify(e).includes("hook-handler.js"));
+  if (kept.length) d.hooks[type] = kept; else delete d.hooks[type];
+}
+fs.writeFileSync(p, JSON.stringify(d, null, 2) + "\n");
+'
 ```
 
+`~/.claude/agent-dashboard/` still holds the SQLite database after all of the
+above — delete that directory too only if you want the recorded history gone.
+
 ## Available Plugins
 
 ### 1. `ccam-analytics` — Analytics & Monitoring