feat(plugin): a Claude Code plugin for context-guru, with the #141 review's blockers fixed

[amiddavid]

Split out of #141, as the review asked. All six of its blocking findings were in the plugin, and none of them were in the release plumbing or the conformance work — so those stay in #141 and can land without waiting for this.

Stacked on #141 (it needs the --listen and --version flags, and the expand-injection gate). Merge #141 first.

The six blocking findings

#	Finding	Fix
1	uninstall killed the user's own session and left the proxy running	pidfile + socket-owner fallback; --listen puts the port in argv; no pattern matching
2	install.sh could not install, and its documented go install fallback was absent	implemented, plus download_failed as a reported outcome and a key=value contract that curl no longer breaks
3	A dead proxy hangs silently and status cannot diagnose it	new UserPromptSubmit hook — the only thing that runs without a model call
4	cache advertised context_guru_expand	fixed in #141, where the gate belongs; the wrong claims here are corrected
5	The backup destroyed the user's undo; uninstall did not restore what it replaced	O_EXCL + microsecond stamps; the replaced value is recorded and restored
6	The atomic write widened a credential file's mode, and replaced symlinks	mode preserved, path resolved first

On finding 1, the mechanism is worth repeating because the fix follows from it: the port was passed through LISTEN_ADDR in the environment, so pkill -f "context-guru-proxy.*$PORT" matched no proxy — and did match the shell running it, which is the session's own Bash tool. The narrow pattern the skill offered as the safe alternative was the one that bit. So the fix is a handle, not a better pattern: a pidfile, a socket-owner fallback, and a check that the PID is ours before killing it.

On is_ours, I did not take the review's suggestion. It proposed matching http://(127.0.0.1|localhost|[::1]):\d+/anthropic as ours, so that changing the configured port stops reporting a conflict against context-guru itself. A test caught why that is unsafe: litellm's default is http://127.0.0.1:4000/anthropic, so a URL-shape rule lets uninstall delete somebody else's routing — and the existing test asserting exactly that started failing. Two local proxies are indistinguishable by URL, so add now records the URL it wrote and later runs read that record. Anything unrecorded stays a conflict, for add and remove alike. Same outcome for the port-change case, without the claim.

Smaller items, all addressed

The dead dashboard link (it advertised /dashboard/ and never passed --dashboard — a 404 as the first line the plugin ever prints; now served, with its database outside the user's repository); backups pruned to 10; the upgrade path documented; --idle-exit's 24h identified as the plugin's value rather than the flag's default; and the zero-value conditions stated where a first-run user reads them — including the one that was documented nowhere and is the commonest for a casual trial: outside a git repository there is no environment snapshot, so the saving is exactly zero. /context-guru:status now checks for it, and no longer reads acted: 0 / savings_pct: 0 as a verdict, since those count content removal and this component relocates a breakpoint.

Verification

Scripts tested from Go, so go test ./... and CI cover them. Seven mutations, each proven to have landed in the source before its result was allowed to count, each failing the named test and passing when restored — full output in the commit body.

One process note worth having in the open: my first attempt at the backup mutation reverted only the timestamp granularity and left the O_EXCL retry loop in place, so the filename was still unique and the test passed — proving nothing about the defect. Reverting half a fix is its own route to a vacuous result. The recorded run restores the original function whole, and then the test fails with "both operations reported the same backup path".

Still not verified

The plugin has not been installed into a real Claude Code session end to end, because install.sh resolves a GitHub release and no tag has published assets yet. That is the first thing to do once #141 merges and a tag exists, and I would not point a stranger at the two-command flow before then.

🤖 Generated with Claude Code