Skip to content

fix(mcp): reload Claude Code plugins in place instead of restarting - #917

Open
harrymove-ctrl wants to merge 1 commit into
devfrom
harry/walm-setup-skill-no-restart
Open

harrymove-ctrl wants to merge 1 commit into
devfrom
harry/walm-setup-skill-no-restart

Conversation

@harrymove-ctrl

Copy link
Copy Markdown
Collaborator

Problem

Two things in the setup skill made a first-time install worse than it needed to be. Both were hit in a real session.

1. Claude Code does not need a restart. The skill ended every install with "fully quit and reopen the AI client, on macOS use Cmd+Q". Claude Code applies a newly installed plugin, its MCP server and its lifecycle hooks with /reload-plugins, in the session the user is already in. Sending a user through a full relaunch is a worse hand-off than one slash command, and it is the last thing they read.

2. Rule 8 made agents give up on a restriction they could clear. An agent running in a sandbox gets EPERM when claude plugin install writes ~/.claude/settings.json, because the CLI stages an atomic write through ~/.claude/.cc-writes/. Rule 8 said "stop at the first real blocker and report the exact failure", so the agent stopped and handed the user a list of commands to paste. That is an environment restriction, not a MemWal fault, and the agent's file-editing tools can usually still write the same files.

Changes

apps/app/public/skills/setup

  • Rule 7 now says not to ask for a restart when the client can reload in place, and keeps the restart for the clients that genuinely need it.
  • Rule 8 now asks for a workaround before a blocker is reported.
  • The Claude Code section hands back /reload-plugins and says explicitly not to tell a Claude Code user to quit with Cmd+Q.
  • The Restart section carves Claude Code out.
  • New troubleshooting row for the sandboxed-agent EPERM case, with the manual install: the enabledPlugins entry, the extraKnownMarketplaces entry, and the installed_plugins.json v2 record shape.
  • The final-report template gains a Claude Code variant that leads with /reload-plugins, plus a rule requiring the agent to disclose any workaround it applied.

docs/mcp/claude-code.md

  • The install step is now "Reload and sign in" and uses /reload-plugins.
  • The MCP-only tab keeps the restart, and says why /reload-plugins does not cover a plain claude mcp add.
  • Troubleshooting: /mcp failures and non-firing hooks both point at /reload-plugins, and a new entry covers the sandboxed EPERM install.

docs/mcp/quickstart.md and docs/mcp/reference.md

  • One-line carve-outs so the generic "restart the client" guidance does not contradict the Claude Code page.

Verification

The /reload-plugins behaviour was confirmed against Claude Code 2.1.272, which carries the strings "Run /reload-plugins to activate successfully installed plugins" and "Plugin changes apply when the current response finishes (/reload-plugins is queued)". Its refresh path reconnects plugin MCP servers rather than requiring a new process.

The manual install in the new troubleshooting row was carried out end to end on a sandboxed session. Afterwards claude plugin list reported memwal@memwal-plugins 0.0.13 enabled at user scope, and claude mcp list reported plugin:memwal:memwal connected.

Docs only. No package or runtime code is touched.

The setup skill ended every Claude Code install by telling the user to quit
with Cmd+Q and reopen. That is not needed: Claude Code applies a newly
installed plugin, its MCP server and its lifecycle hooks with
/reload-plugins, in the session the user is already in. Restarting is still
correct for Claude Desktop, Cursor, Codex and Antigravity, and for a plain
`claude mcp add` on Claude Code, so the restart guidance stays for those.

Setup rule 8 also told the agent to stop at the first failing command. A
sandboxed agent hits EPERM on ~/.claude/settings.json and the .cc-writes
temp directory, which is an environment restriction rather than a MemWal
fault, and the rule made agents hand the whole install back to the user.
Rule 8 now asks for a workaround before a blocker is reported, and a new
troubleshooting row documents the manual install: the enabledPlugins entry,
the extraKnownMarketplaces entry and the installed_plugins.json v2 record.

The final-report template gains a Claude Code variant that leads with
/reload-plugins, and a line requiring the agent to disclose any workaround it
applied.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants