Getting started

mu comes two ways: a desktop app that carries everything it needs, and the mu command line. Both share accounts, settings, sessions and lessons, so you can start a task in one and pick it up in the other.

The desktop app

1. Download the build for your system from Releases, or from the home page, which picks your system for you.

   System	File
   macOS, Apple silicon	mu-<version>-mac-arm64.dmg
   macOS, Intel	mu-<version>-mac-x64.dmg
   Windows x64 / Arm	mu-<version>-win-x64.exe / mu-<version>-win-arm64.exe
   Linux x64 / Arm (Debian, Ubuntu)	mu-<version>-linux-amd64.deb / mu-<version>-linux-arm64.deb

   SHA256SUMS on the release page lists the checksum of every file. The macOS builds are signed and notarized by Apple. The Windows builds are not code-signed yet, so SmartScreen warns the first time: choose More info, then Run anyway.

2. Open it. The first-run guide walks through four steps: a model, a permission mode, a judge, and a start.

   • Model. Paste an API key, and mu recognises the service from its shape (DeepSeek, Kimi, Qwen, GLM, SiliconFlow, OpenRouter, OpenAI, Anthropic, Google Gemini, xAI and more) and checks it with one request. Or sign in with a ChatGPT, Claude, Grok or Google subscription. A wrong key, an empty balance, an unsupported region or no connection is each explained with what to do.
   • Permissions. Jev approves is preselected; see Permissions and safety.
   • Judge. With no key, the free Jev answers. You can come back to this any time.
   • Start. If mu finds Claude Code or Codex conversations, it offers to import them.

3. Pick a folder and start a conversation.

Nothing else needs installing: no Node.js, and nothing is downloaded at the first start. When a new release is out, the app tells you its version and size, downloads it only after you agree, and installs it when you restart.

The command line

npm i -g mu-agent      # Node.js 22.19 or newer
mu setup               # connect a model and choose the judge
mu                     # a session in the current directory

mu setup asks step by step, in Chinese or English. If you skip it, the first mu with no model asks once whether to set one up now. For scripts, mu setup --help shows the non-interactive forms; a key is read from standard input, never from the command line.

Some things to try:

Inside a session, /status shows the judge, each decision point's mode and the latest verdicts, and /help lists every command. The command line page has the full list.

Your first task

Open a project folder and say what you want done, in your own words. What happens next:

1. Jev reads your message first and shows a one-line verdict, such as multi-step task · heavy gear. This takes well under a second; press Esc to skip it.
2. The model works. Long tool output is filtered before it reaches the model; commands outside the project wait for approval in the Jev approves mode.
3. When it says it is done, mu checks whether anything verified the work, and nudges it once if not.

To keep it going until a condition holds, use goal mode: /goal all tests in packages/api pass.

The judge

mu asks a small, fast judge the routine questions of a session. You do not have to set one up: with no Jev key, the free Jev on OpenCode Zen answers, and mu says so once a day. To use your own key, a local judge or another model, see Judges.

Every decision point acts on its verdicts from the start, and each verdict is logged: /status, mu ledger, or the judgments tab in the app. To watch the judge before trusting it, put the decisions in shadow mode: they are still asked and logged, but change nothing.

{ "modes": { "default": "shadow" } }

That goes in ~/.mu/agent/mu.json; /mu mode default shadow does the same for the current session only.

Where things live

On Windows, ~ is your user folder (%USERPROFILE%).