Quickstart

Get Muse Code running in minutes.

Muse Code is generally available for macOS, Linux, and Windows. It takes on complex software engineering tasks across large repositories — planning changes, writing code, and validating the results — entirely from your terminal.

1. Install

One command installs the CLI:

$curl -fsSL https://dev.meta.ai/install.sh | bash

The script drops the muse binary into your PATH — verify with muse --version. Prefer to review the script first? Download it with -o install.sh, audit, then run.

Windows

Windows has its own native installer: run irm https://dev.meta.ai/install.ps1 | iex in PowerShell, then check it with muse --version. On Windows the agent runs commands in PowerShell instead of Bash, the sandbox may show a UAC prompt the first time it starts, and voice input and inter-session messaging aren’t available. If you want those, or a Bash toolchain, use WSL2 instead: run wsl --install in an administrator PowerShell, then run the macOS/Linux installer inside the Linux shell. Keep those repositories on the Linux filesystem (for example ~/code), not under /mnt/c, because file access across that boundary is much slower.

2. Authenticate

Your first run opens the browser to authenticate at dev.meta.ai with your Meta developer account. Credentials cache locally — no re-auth per session. Usage bills to your monthly plan or, on pay-as-you-go, to the Meta Model API.

Non-interactive runs. For CI, scripts, and headless machines, use an API key instead of the browser flow: create one in the Model API dashboard (API keys → Create API key) and either export it as META_API_KEY or store it with muse auth set. Keys start with LLM_. Muse Code checks META_API_KEY first, then a stored key, then a browser session; /login reopens the sign-in options and muse logout clears stored credentials.

3. Run your first task

Once auth is done, you’re free to get started in any of your project directories:

$ cd my-repo$ muse

Describe the outcome you want in plain language. A good first task is small and verifiable — “add a missing test for parseDate and make sure it passes” — you’ll see a worker draft the change, a reviewer critique it, and the test run.

Two cost levers worth knowing from day one: Muse Spark is a reasoning model — it thinks before it answers, and those tokens bill as output — so /effort dials the thinking up or down per task. And your tone, format, and other standing rules can live in a system message so you don’t repeat them in every prompt.

Update & uninstall

Muse Code updates itself: the installer sets up a launcher that keeps the binary current, and since CLI 1.4.11 a session left running through an auto-update resumes with its history. Check what you have with muse --version and compare it with the changelog; rerunning the install command also gets you the latest build. Meta doesn’t document an uninstall command. On macOS and Linux the installer puts the launcher in ~/.local/bin (muse, plus versioned muse-bin-* files) and adds that directory to your shell profile, so removing those files uninstalls it; settings live in ~/.config/muse/. On Windows, Get-Command muse shows where the binary is. Cancel any subscription separately in Accounts Center — deleting the CLI doesn’t stop billing.

Async background agents

Muse Code operates with a simple agent loop plus a set of async background agents that enhance the main agent’s capability. These specialized agents remain active throughout each session rather than being spawned per task, which avoids redundant information gathering. They carry out next steps on their own and choose when to communicate back to the main agent — their persistence reduces latency and the need for steering on difficult, multi-step tasks.

Agent fan-out & git worktrees

When a job splits into several tasks, they fan out automatically to separate agents: the parent spawns a write-capable child per task, and each child gets its own git worktree — so parallel children never collide on the same files and your working copy stays clean.

Workflows

Added when Muse Code left beta, Workflows orchestrate a team of specialized agents across a larger job: each stage hands its intermediate work to the next, and you get a single result at the end. Start one by asking Muse Code to “use a workflow”; setting effort to ultra can trigger one automatically. /workflows shows every run live — stop, restart, or cancel it there — and saved workflows can be reused.

Inter-session messaging

Sessions running on the same machine can message each other over a local Unix socket. When a change in one session affects what another is building, it passes a warning across; when one session settles a question another is blocked on, it sends the answer — no retyping between terminals. The agent discovers its peers and sends messages with two built-in tools.

Event log & rewind

Muse Code uses a local event log to which every model call, tool run, approval, and edit is appended. This single source of truth makes the runtime replay-exact and restart-safe: after a crash, the agent resumes precisely where it stopped, letting it take on long-running tasks without being derailed by failures. Every subagent spawn, steer, and cancel is observable — muse replay walks a session step by step, and full traces export for handoff or audit. Press Esc twice to rewind the conversation to an earlier point; Muse Code only offers rewind points the event log marks as safe.

Bundled skills & commands

Muse Code ships with several default skills — put a rough idea in, get a grilled, taste-checked feature out:

/planTurns a task into an approval-gated plan before any code changes
/grillStress-tests that plan until it holds up
/goalWorks toward successful completion of the specified objective — what you originally wanted is what gets merged
/workflowsLists workflow runs live — stop, restart, or cancel any of them
/modelSwitches the backing model — e.g. to muse-wonder-1.0; the picker also sets the reasoning level
/effortDials reasoning up or down — thinking tokens bill as output, so save deep reasoning for hard tasks
Esc EscRewinds the conversation to a safe point from the event log
muse replayWalks a session's event log step by step; full traces export for handoff or audit

Permissions & approval modes

Muse Code starts with approvals and an OS sandbox on (Seatbelt on macOS, bubblewrap on Linux, the Windows sandbox on Windows). Writes are limited to the workspace and a temp directory, and .git, .muse, and .agents stay read-only. New sessions start in the Auto-review profile, where a built-in judge decides routine approval requests and hands the rest to you; the other profiles are Ask me, Read-only, and Unrestricted. Set the default with permissions.default_profile in ~/.config/muse/settings.json. The flags that matter:

--approval-mode on-requestDefault. Safe shell stages run; dangerous ones such as rm -rf stop for review
--approval-mode untrustedStricter: any shell stage without a matching allow rule stops for review
--approval-mode neverNothing stops for approval; the sandbox alone contains what runs
--disable-approvalSkips approval prompts but keeps the sandbox on
--yoloNo approvals, no sandbox, workspace trusted. Meta says to use it only in disposable, isolated containers
--sandbox-networkproxy-only (default, approves each destination), restricted, or unrestricted

When a command is held, you can allow it once, always allow it in this workspace, or reject it. MCP tools and hooks run outside the sandbox, so connect only servers you trust.

Muse Spark 1.3

Muse Spark 1.3, released September 2, 2026, is the model behind Muse Code. It keeps the training recipe that set 1.2 apart — co-training with the Muse Code harness, extensive long-horizon work, and a self-improvement loop — and focuses on real-world usability. Pricing is unchanged from 1.2. Three things stand out:

Longer threads
Sustains longer-horizon work across multiple workflows in a single thread, carrying context from one stage to the next.
Asks instead of guessing
Collaborates more actively: it asks clarifying questions, flags when it’s stuck, and is better calibrated about its own limits instead of reporting outcomes it didn’t reach.
Leaner runs
In Meta engineers’ comparisons it finished the same coding work with about 20% fewer tool calls and 25% fewer tokens than 1.2 — at the same per-token price, that is a smaller bill.

Benchmarks (max reasoning configuration, per Meta): DeepSWE 1.1 · 75.4% — Terminal-Bench 2.1 · 88.8% — SWEAtlas CodeBase QnA · 59.4%. At launch the max configuration was still in safety testing; the configuration most developers get scores lower. Methodology at research.meta.ai.

Muse Wonder

Muse Wonder and Muse Wonder Full, released October 12, 2026, are Meta’s first frontier models: larger than Muse Spark and aimed at long, hard work in coding and in fields like law and finance. Meta highlights Active Memory, which carries relevant context across conversations, and Active Focus, which keeps an agent working toward a goal and checks in before important actions. Switch to Wonder with /model muse-wonder-1.0; on the API it costs $4 / $0.20 / $20 per 1M input / cached / output tokens, with no Contributor variant. Muse Wonder Full comes only with the Power and Maximum plans.

Muse Spark Open

Released October 15, 2026, Muse Spark Open is an open-weight Muse model: 816B parameters in total, 42B active per token, a 1M-token context, and text, image, video, and audio input. It ships under Meta’s Muse Model License, a custom license, and the weights are on Hugging Face as meta-models/Muse-Spark-Open-816B-A42B. It is not a laptop model: it needs about 700 GB of accelerator memory in NVFP4. Meta has shown Muse Code running on it across two Mac Studios but hasn’t documented a local setup. For a model that fits one consumer GPU, see Muse Glimmer.

Case study: kernel optimization

Meta tested Muse Spark 1.2’s ability to iteratively optimize GPU kernels over 1,000+ tool calls — up to 24 hours. Inside Muse Code’s agentic environment, the model writes, compiles, profiles, and progressively improves kernel performance against a baseline, benchmarked on KDA and MLA kernels for NVIDIA Hopper GPUs. Barred from wrapping third-party kernel libraries, it implemented the algorithms in Triton directly — and kept finding substantial improvements over the baseline.

Meta Model API

The same models behind Muse Code are available directly — `muse-spark-1.3` and `muse-wonder-1.0` are on the Model API, and Muse Spark 1.3 also ships in Muse Code, the Meta Model API, OpenRouter, and Cursor. The API is drop-in compatible with the OpenAI SDK, the Anthropic SDK, and agent CLIs like OpenCode and Claude Code: point your client at the base URL and keep the rest of your code. The context window is 1,048,576 tokens.

# export MODEL_API_KEY="LLM_..."client = OpenAI( base_url="https://api.meta.ai/v1", api_key=os.environ["MODEL_API_KEY"], ) response = client.chat.completions.create( model="muse-spark-1.3", messages=[{"role": "user", "content": "Hello, world!"}], )

Headless & CI

muse exec "<prompt>" runs one task to completion and exits — the form to use in scripts and CI. Add --json for JSONL events on stdout, --prompt-file to read the prompt from a file, --max-model-steps to cap the work, and --session-id to continue an earlier session. Authenticate with META_API_KEY from your CI secret store. Exit code 0 means the turn finished, not that the work is correct, so gate merges on your own tests. On Linux runners the sandbox needs bubblewrap and a non-musl build.

# CI: key from your secret store, JSONL events on stdout$ META_API_KEY="$MUSE_KEY" muse exec --json "fix the failing test in tests/date.test.ts"

Muse models in other agents

Meta documents setups for OpenCode, Codex, and Claude Code against the Model API. Use the OpenAI-compatible base URL https://api.meta.ai/v1 (for OpenCode and Codex) or the Anthropic-format base URL https://api.meta.ai with no /v1 (for Claude Code), your MODEL_API_KEY, and a model ID such as muse-spark-1.3 or muse-wonder-1.0. In Claude Code, set ANTHROPIC_AUTH_TOKEN rather than ANTHROPIC_API_KEY, and point every model alias at a Muse model so nothing falls back to Claude. In Codex, use wire_api = "responses" so reasoning carries across turns. This bills per token on the Model API; your Muse Code plan doesn’t cover it.

# Claude Code on Meta's Model APIexport ANTHROPIC_BASE_URL="https://api.meta.ai"export ANTHROPIC_AUTH_TOKEN="$MODEL_API_KEY"export ANTHROPIC_MODEL="muse-wonder-1.0"export ANTHROPIC_DEFAULT_OPUS_MODEL="muse-wonder-1.0"export ANTHROPIC_DEFAULT_SONNET_MODEL="muse-spark-1.3"export ANTHROPIC_DEFAULT_HAIKU_MODEL="muse-spark-1.3"export CLAUDE_CODE_SUBAGENT_MODEL="muse-spark-1.3"

Muse Code SDK

In developer preview since Muse Code left beta, the SDK lets teams build their own agents on the Muse Session Protocol (MSP) — an open protocol over standard I/O with no server and no network, so everything stays on your machine. The TypeScript library covers sessions, tools, and permission control, and MSP’s machine-readable schema lets you generate clients in other languages. Source: github.com/meta-models/muse-code-sdk.

Cookbook

Recipes that run the first time you copy them — each one solves a focused problem, shows working code, and points to what’s next. Three sections, plus recipes for Muse Code’s core patterns.Browse all 28 recipes →

API fundamentals · 10 recipes
Prove each primitive works: chat completions, streaming, tool calling, structured output, prompt caching, reasoning tokens, vision input, long context, error handling, and search grounding with inline citations.
Agent patterns · 5 recipes
The loops that turn a model into an agent: the perceive-decide-act loop, interleaved reasoning and tool use, multi-turn context management, and validated in-place edits.
Use cases · 13 recipes
End to end: browser-verified web design and game dev, a four-profile multi-agent product studio coordinating through a shared Kanban board, an autonomous GitHub Actions bot on OpenCode, computer use on Linux and macOS, and more.
Muse Code recipes
Agent fan-out — split one big job across subagents in isolated worktrees; bundled skills — a rough idea in, a grilled, taste-checked feature out; goal tracking — keep an agent on task until it merges what you wanted.