Skip to content

docs: add warning and termination commands to prevent Claude config reset#306

Open
raphy0316 wants to merge 5 commits intorobotmcp:developfrom
raphy0316:docs/claude-config-warning
Open

docs: add warning and termination commands to prevent Claude config reset#306
raphy0316 wants to merge 5 commits intorobotmcp:developfrom
raphy0316:docs/claude-config-warning

Conversation

@raphy0316
Copy link
Copy Markdown

@raphy0316 raphy0316 commented Mar 30, 2026

Description

This PR updates the Claude Desktop setup guide to add a crucial warning regarding the configuration step.

Currently, if a user modifies claude_desktop_config.json while Claude Desktop is still running in the background, the configuration fails silently and gets wiped/reset the moment they enter the chat window.

To prevent users from wasting time debugging their MCP server or ROS connections, this PR adds explicit instructions to completely terminate the background process before editing the config, plus troubleshooting for caching issues.

Changes Made

  • Added a ⚠️ Important warning note in docs/install/clients/claude-desktop.md explaining the silent overwrite behavior
  • Added platform-specific termination commands:
    • Linux/macOS: pkill -f claude-desktop
    • Windows: Task Manager instructions
  • Added caching troubleshooting note in the "Verify the Setup" section

Platform Note

I originally encountered and reproduced this silent reset issue on Windows 11 (Claude v1.1.9493.0). This PR now includes explicit termination instructions for all platforms (Linux/macOS/Windows).

Related Issue

Resolves #291

Copy link
Copy Markdown
Contributor

@sbae56-art sbae56-art left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The warning is necessary, but i think this need to a small revision before approve. The same config block appears to be copied into multiple OS section, and "p kill f claude desktop" was also shown in Windows related section.

Copy link
Copy Markdown

@Tyrrnien81 Tyrrnien81 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've run into this silent config reset issue myself, so this warning is a useful addition. The core message about quitting Claude Desktop before editing the config is clear and correct.

I agree with @sbae56-art's observation. A couple of things I noticed:

  • pkill -f claude-desktop is a Unix command, so it won't work in the Windows (Native) section as-is.
  • The warning line has a missing opening backtick before claude_desktop_config.json (shows up in all four sections).

These are minor and can be fixed in a follow-up. Approving since the main fix is solid.

@mokcontoro
Copy link
Copy Markdown
Contributor

@raphy0316 could you please fix the merge conflict?

@raphy0316
Copy link
Copy Markdown
Author

@mokcontoro I've resolved the merge conflicts. I noticed that the docs were split across multiple sections, so I updated and added the changes to the appropriate parts accordingly.

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.

5 participants