Troubleshooting

When something looks wrong

Start with muon doctor (machine-readable JSON, safe to script against) or muon onboard (the human-guided version). Both are read-only diagnostics and never reject on a degraded environment — every source that can't be read degrades to an honest “unknown” with a reason instead of a crash.

muon doctor --json     # scriptable capability preflight
muon onboard           # guided, human-readable checklist

A vendor CLI isn't found, or reads as logged out

MUON checks two things separately per vendor — installed and authenticated — and both muon doctor and muon onboard name which one is missing rather than a generic “not ready.”

Vendor	Reinstall	Re-authenticate
Claude Code	`npm i -g @anthropic-ai/claude-code`	run `claude`, sign in
Codex	`npm i -g @openai/codex`	`codex login`
Cursor	`curl https://cursor.com/install -fsS \| bash`	`cursor-agent login`
OpenCode	`curl -fsSL https://opencode.ai/install \| bash`	`opencode auth login`

Codex with a custom provider

If ~/.codex/config.toml selects a custom model_provider (e.g. Azure), MUON requires the exact env_key that provider declares — a cached native login does not authenticate a different selected provider. Set the provider's key in your shell environment (never a repository file) and launch MUON from a shell that has it, or switch back to a built-in provider and run codex login.

Each lane holds the roles it is best at, by design: Cursor takes review-class roles with a no-writes guarantee, and OpenCode scouts. If a dispatch is refused for a role, that is the role model working, not a fault.

The code index looks stale

MUON's embedded code graph indexes your workspace in the background as you commit. Check whether it has fallen behind HEAD:

muon version

The JSON includes brainCommit (what the graph is indexed at), headCommit (your actual HEAD) and stale (whether they disagree).

In the desktop app, open the graph/code panel and use Re-index — it's disabled while an index is already running, since indexing is exclusive per repository.
The MCP server opportunistically refreshes freshness on certain reads (code_impact), so a short lag often clears on its own.
A stale index degrades gracefully rather than lying: the orchestrator treats a stale or unindexed file as review-blind and routes it to a human rather than certifying a diff it can't see.

The brain doesn't seem to be running

“The brain” is MUON's embedded local backend. The desktop app supervises its own; the CLI auto-spawns one on first use for every command except version, shutdown, custom-agents and most mcp subcommands, which are deliberately brain-independent.

muon doctor          # reports connectivity honestly, even if the brain is down
muon mcp status      # whether a brain is running, and its port/pid
muon shutdown        # stop the CLI-spawned brain + runner cleanly
muon chat            # any ordinary command re-spawns one if none is found

If the desktop app and a CLI-spawned brain both start, MUON detects and adopts the already-running one rather than starting a second — muon doctor tells you which profile you're actually talking to.

Where logs live

Path	What
`…/MUON/logs/brain.log`	Embedded backend log
`…/MUON/logs/runner.log`	Sandboxed runner boot, lease, dispatch and recovery log
`~/Library/Application Support/MUON/`	Everything else MUON persists locally — settings, the embedded SQLite brain, the graph store, the lockfile

How to reset

01
Stop everything cleanly first
Quit the desktop app, then run muon shutdown to stop any CLI-spawned brain and runner. Confirm nothing is left with muon doctor.
02
Wipe local state
Delete ~/Library/Application Support/MUON/. This removes the embedded brain, the graph store, the lockfile and settings — including unconfirmed memory proposals. Export first with muon memory pack export --out <dir> if you want confirmed decisions back afterwards.
Removing the data directory by hand is the current reset path — there is no muon reset command in v1.
03
Relaunch
Reopen the app or run any muon command; MUON reinitializes a fresh brain and re-indexes the workspace the next time it needs to.

Still stuck?

Send a mail with your muon doctor --json output attached — it never includes a credential value, only readiness booleans and reasons — to abhinavpandey1230@gmail.com.

Previous← Governance