Basemind Doctor

basemind-doctor — diagnose and recover basemind

Use this when basemind isn't behaving: MCP tools aren't available or return errors, the statusline says no index, queries come back empty when they shouldn't, or the basemind serve MCP server appears dead. Every step here uses the CLI, so it works even when the MCP server is down.

Important: a stdio MCP server (what basemind serve is) cannot be restarted by an agent or by basemind itself — a fresh process can't resume the client's MCP initialize handshake. Reconnecting the server is the MCP client's job (see step 4). What you can do from here is make sure the index is healthy and clear anything blocking a restart.

1. Is there an index?

basemind admin status

• Errors / "no index" / file_count: 0 with blobs present → the index is missing or lost. Build it: basemind scan (see the basemind-scan skill / /bm-scan).
• Healthy file_count → the index is fine; the problem is the server connection (step 4).

2. Is a server already running (holding the lock)?

If basemind scan fails with a lock error, a basemind serve (or watch) already owns the index for this repo. The lock-contention error itself names the live holder (command + pid) — it reads that from the .lock.meta sidecar next to the workspace .lock. Both live in this workspace's directory under the machine-global cache (Linux ~/.local/share/basemind/, macOS ~/Library/Application Support/basemind/; override BASEMIND_DATA_HOME), keyed by workspace — not in the repo.

• If that pid is alive (ps -p <pid>), the server is up — use the MCP tools, or the admin { mode: "rescan" } to refresh. Don't run a CLI scan (it will contend on the lock).
• If that pid is dead, the lock is stale. The OS releases the advisory lock when a process dies, so a fresh basemind scan / basemind serve should just work — retry it. (You may delete the stale .lock.meta sidecar in that workspace cache dir to clear the advisory holder record.)

3. Rebuild the index if needed

basemind scan

Non-extractable files are skipped, not failed. After this, both the CLI and (once reconnected) the MCP tools have a fresh index.

4. Reconnect the MCP server (client-specific — this is the only way to restart it)

basemind can't relaunch its own stdio server; trigger a reconnect in your client:

• Claude Code: reconnect the basemind MCP server from the MCP UI, or restart the session. The plugin's launcher re-downloads/execs the binary automatically on the next connection.
• Cursor / others: toggle/reconnect the basemind MCP server in the MCP settings.

While disconnected, you are not blocked: use the basemind-cli skill (basemind code …, basemind git …) — it reads the same machine-global cache directly, no server required.

Agent shells (embedded rmux daemon)

Only when the server was built with --features shells. Spawned shell sessions run under an embedded rmux daemon — basemind re-execs itself (--__internal-daemon) rather than shelling out to any external rmux binary, so there is nothing extra to install. The daemon binds a private per-user socket under the data dir (<data_dir>/basemind/shells/rmux.sock, 0o700), overridable with BASEMIND_SHELLS_SOCKET. It is separate from the comms broker daemon.

• shell { mode: "list" } enumerates sessions with liveness; a dead-but-listed session was killed or exited — re-run after shell { mode: "kill", session_id: "…" } to confirm it's gone.
• The daemon self-terminates once it has no sessions left, so an idle daemon disappearing is expected, not a fault. shell mode spawn starts a fresh one.
• Sessions are independent of serve: they outlive a single MCP call but are torn down by shell mode kill (which also drops the comms lineage row) or when the daemon exits.

When server logs help

basemind serve logs its lifecycle to stderr (captured in your client's MCP server logs): a MCP server starting line with pid/version/view at startup, and an explicit client disconnected, exiting (clean) or exiting on error (with the cause) at shutdown. If serve keeps dying, that log line names the reason.