Troubleshooting

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 codex login.

Each lane holds the roles it is best at, by design: Cursor takes review-class roles (reviewer, QA, architect, scout) 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 workspace's actual HEAD), and stale (whether they disagree). If it's stale:

In the desktop app, open the graph/code panel and use the Re-index button — it's the operator's explicit escape hatch and is disabled while an index is already running (indexing is exclusive per repository, so two triggers can't race each other into a corrupted store).
The MCP server also opportunistically refreshes freshness on certain reads (code_impact), so a short lag often clears on its own during normal use.
A stale index degrades gracefully rather than lying: MUON's own orchestrator is instructed to treat a stale or unindexed file as review-blind and route it to a human rather than certify a diff it can't actually 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, since some of them exist specifically to diagnose a brain that isn't there).

muon doctor          # reports connectivity honestly, even if the brain is down
muon mcp status      # reports 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 up, MUON detects and adopts the already-running one rather than starting a second — running muon doctor tells you which profile (data directory, port, pid) you're actually talking to.

Where logs live

Path	What
`~/Library/Application Support/MUON/logs/brain.log`	Embedded backend log
`~/Library/Application Support/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

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.
Wipe local state
Delete ~/Library/Application Support/MUON/. This removes the embedded SQLite brain, the graph store, the lockfile, and settings — everything MUON knows locally, including unconfirmed memory proposals. Confirmed decisions you care about should be exported first with muon memory pack export --out <dir> if you want them back afterward.
No dedicated reset commandRemoving the data directory by hand is the current reset path — there is no muon reset command in v1.
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) at abhinavpandey1230@gmail.com.