Skip to content

Repair

Troubleshooting

Fix the common setup issues: daemon not running, MCP not connected, missing Claude commands, stale context, and support escalation.

Qi-Xuan LuUpdated 5 min read

At a glance

01

Start with /init in Claude Code, wenlan doctor in the terminal, or the doctor tool in an MCP client.

02

Most issues are one of three things: daemon not reachable, MCP server not configured, or the client needs a restart.

01

Claude Code commands are missing

If /brief, /capture, or /handoff do not appear after installing the plugin, restart Claude Code once.

Then run /init. It should verify the plugin, daemon, MCP route, and memory round trip.

Claude Code

/init

02

Daemon is not reachable

Wenlan's daemon listens locally on port 7878. If a client cannot reach it, use /init from Claude Code or the doctor tool from an MCP client to check the daemon state.

For non-Claude clients, rerun npx -y wenlan setup if the local runtime was never installed or status verification failed.

Only one daemon should own the local database. If you have been developing Wenlan locally, make sure an old daemon from another checkout is not still running.

03

MCP client is not connected

Check that you ran npx -y wenlan setup first, then ran ~/.wenlan/bin/wenlan mcp add for that client. Some clients require a full restart after changing MCP settings.

If the client shows the server but tools fail, run doctor. It reports whether the daemon is reachable and how setup is configured.

MCP config

{
  "mcpServers": {
    "wenlan": {
      "command": "/Users/you/.wenlan/bin/wenlan-mcp"
    }
  }
}

04

Recall returns weak context

First make the recall query more specific. Include project names, feature names, decisions, people, or the exact failure mode.

If the memory exists but is stale or duplicated, use /review for pending queues and /distill when a topic deserves a clearer page.

05

When to open an issue

If /init or doctor reports a daemon, MCP, or install failure you cannot resolve, open a GitHub issue with the client name, command you ran, and the diagnostic output.

Avoid pasting private memory contents into public issues. Describe the setup failure and redact project-specific details.

Open a GitHub issue

Next

Diagnostics and Issue Reports

Run the right checks before asking for help, separate daemon problems from client problems, and share only redacted output.

Read next