Use Muse Code inside Zed — and any ACP editor

muse-code-acp connects Muse Code to Agent Client Protocol (ACP) clients like Zed and VS Code with an ACP extension, so you get streamed tool calls, editor-native permissions, plan mode, sessions, MCP, and slash-command workflows — without leaving your editor.

⚡ Quickstart · ✨ Features · 🏗️ How it works · 📖 Docs · ⭐ Star on GitHub

npm install -g @bex-co/muse-code-acp

Unofficial adapter. Muse Code and Muse Spark are products of Meta Platforms, Inc. This community project is not affiliated with, endorsed by, or supported by Meta. You install Muse separately — this package does not bundle the Muse executable.

---

💡 Why developers use it

Coding agents are only useful where you actually write code. muse-code-acp brings Muse into the editor surface ACP was designed for:

• Stay in your editor — streamed replies, tool calls, diffs, and permission prompts render natively in Zed / your ACP client, not in a separate terminal UI.
• Keep control — Default, Read-only, and guarded Plan modes; every approval is a host-offered choice routed through ACP and fails closed on cancel or stale replies.
• Keep your sessions — list, load full history, resume without replay, close, and natively fork Muse sessions from the client.
• Bring your tools — client-provided MCP servers (stdio + HTTP), images and embedded context, model switching, skills, planning, Git reviews, and goals.
• Trust what's verified — behavior is pinned to a verified Muse host, covered by deterministic contract tests plus required real-host loopback suites in CI. Limits are stated plainly below, never hidden.

⭐ If this saves you setup time, star the repo — it helps other ACP + Muse users find it, and open an issue with your editor + Muse version when something breaks.

✨ What you get

On the default SDK backend with the verified host:

You get	Details
💬 Streamed agent	Text, tool calls/results, cancellation, multi-turn continuity
🖼️ Rich context	PNG/JPEG/GIF/WebP images, resource links, embedded text (audio/binary resources unsupported)
🧭 Sessions	Paginated list, full history load, resume without replay, close, native fork
🔐 Permissions	Interactive host-offered choices via ACP; cancel/stale replies fail closed
🎛️ Modes & models	Default / Read-only / Plan; provider- and profile-qualified model catalogs, /models refresh, verified idle model switching
🔌 MCP	Client stdio + HTTP servers, with local config/last-failure diagnostics
📝 File changes	Bounded observed diffs; optional negotiated reports mark partial coverage
⚡ Slash workflows	Skills as slash commands, /plan, /review, goals, and more (below)
🎯 Goals	Goal status; native /goal set|edit|pause|resume|clear on Muse 1.4.6+
↪️ Mid-turn steering	When explicitly negotiated by the client

Slash commands worth trying first

Slash commands can appear in any top-level text block alongside editor context.

Command	Try it for
/plan <task>	Guarded planning first; /plan alone enables Plan mode without starting
/review <focus>	Git review with focus instructions; attachments preserved
/goal <task>	Run a task once; /goal set <objective> for a persistent native goal (1.4.6+)
/models	Refresh the model catalog before a turn
/recap · /rename	Native session recap / rename on Muse 1.4.7+
/compact	Native context compaction on Muse 1.4.12+
/skills · /plugins · /hooks	Inspect, enable/disable, and import skills; list/install plugins (1.4.7+)
/status · /mcp <question>	Session + subscription usage; MCP diagnostics combined with a normal task
/feedback bug|bad|good|other <note>	Send feedback to Muse (session record only with --with-session)

Full slash-command notes

On Muse 1.4.7 or newer, /recap asks Muse for a short recap of the session (a model side-call that adds nothing to history) and /rename also sets Muse's own session name. /skills enable|disable <skill> changes a skill's activation in the scope it comes from, /skills import claude|codex previews importing foreign skills (--apply imports), and /feedback bug|bad|good|other <note> sends feedback to Muse with no files attached (the session record only with --with-session). /status also shows Muse's own subscription usage when Muse reports it. On Muse 1.4.12 or newer, /compact asks Muse to compact the session's context and reports the outcome (clients advertising session.compaction also get standard compaction updates); Muse's refusals are reported verbatim. /plugins and /hooks list installed Muse plugins and hooks, and /plugins install <folder> installs a local plugin, only on that explicit command.

Planning and review preserve attachments. /goal <task> runs the task once without creating a goal; /goal set <objective>, edit, pause, resume and clear control Muse's native goal on Muse 1.4.6 or newer (see goal controls). Local status queries do not send attachments to a model; an additional explicit task is handled after the status response. /mcp <question> combines local diagnostics with a normal task in the current mode, without claiming native MCP control.

Honest limits: delegated workers and token usage are reported as unavailable. Reasoning summaries, editor-side filesystem proxying, multiple authorized workspace roots, and native session deletion are not implemented. Closing a session retains its native history. This adapter does not implement every ACP feature or every feature of Muse's terminal UI. Available features also depend on your ACP client.

⚡ Quickstart — about 60 seconds

Prerequisites

• Node.js 22+
• Muse Code 1.1.1-R2514.1 (verified host, installed separately, with muse serve) — the latest Muse installer may install a different version, so pin the binary with MUSE_CODE_EXECUTABLE (see Compatibility)
• Muse auth via browser login or META_API_KEY

export MUSE_CODE_EXECUTABLE="/absolute/path/to/muse-1.1.1"
"$MUSE_CODE_EXECUTABLE" --version
"$MUSE_CODE_EXECUTABLE" serve --help
"$MUSE_CODE_EXECUTABLE" login
npm install -g @bex-co/muse-code-acp
muse-code-acp --version

For headless use, provide META_API_KEY to the adapter process instead of browser login. The adapter speaks ACP over stdio — launch it through your editor, not as an interactive terminal chat.

Zed

Add a custom external agent to your Zed settings, replacing the Muse path:

{
  "agent_servers": {
    "Muse Code": {
      "type": "custom",
      "command": "muse-code-acp",
      "args": [],
      "env": {
        "MUSE_CODE_EXECUTABLE": "/absolute/path/to/muse-1.1.1"
      }
    }
  }
}

Then select Muse Code in Zed's Agent Panel and send your first prompt — try /plan explain this repo to see Plan mode in action.

Tip — GUI apps don't inherit your shell. Set MUSE_CODE_EXECUTABLE (and META_API_KEY, if used) in the editor config even if you exported them in a terminal. If Zed cannot find muse-code-acp, use its absolute path as command; Node must also be available to the editor.

Other ACP clients use the same command and env. Browser login inside a client requires terminal-auth support; otherwise authenticate beforehand.

🏗️ How it works

Zed / VS Code (ACP client)
        ↕  ACP over stdio
muse-code-acp  (this adapter)
        ↕  official Muse SDK (@muse-code/sdk, pinned)
muse serve  (MSP)  →  native sessions, tools, sandbox, models

The official Muse SDK communicates with muse serve over MSP. The adapter starts or resumes native sessions, translates message/tool items into ACP updates, routes permission requests to the client, and cancels using turn/cancel. Native execution, model access, persistence, and sandboxing remain owned by Muse.

• Modes, two ways in sync. Mode selection works through ACP config options and the legacy session-mode interface; changing either keeps both synchronized, and /plan updates the mode selector. SDK sessions offer Default, Read-only, and Plan. These are not Codex's "Approve for me" or "Full access" presets — native automatic approval has not been verified on the supported host (allowAll was accepted in isolated tests, but a shell write still required a decision). Remaining approvals are forwarded, never auto-granted.
• Session hosts. Each SDK session can retain its host across compatible turns. Idle hosts expire after 60 seconds; session close also releases them. Close a session before moving its native conversation to another client. Listing uses public session/list with bounded pagination; full history replay uses validated muse export; read-only store helpers remain for compatibility lookups and title fallback. Indexes are eventually consistent, so a new session may not appear immediately.

Permissions deep dive: multi-stage approvals, stalls, and session state

A shell command can need more than one approval: Muse splits a compound command into stages and asks about each one that is not already known-safe. The adapter decides every stage from the host's latest published requirement, so one tool call produces one permission request per unresolved stage and runs only after the last decision. Denying any stage cancels the whole command. Only choices the host offered are ever submitted. Each multi-stage prompt shows the current stage's host-published arguments and position, such as Stage 3 of 4: echo two, even without a Muse extension. The total includes known-safe stages, not just dialogs. The full command remains available in the request; the adapter does not parse shell text to invent a stage. Single-stage prompts keep their existing titles.

If the host stops making progress on a request the adapter owes it an answer to, the turn fails after MUSE_CODE_ACP_STALL_MS with the approval, requirement and stage evidence, rather than waiting indefinitely. Clients also receive a muse/hostCompatibility entry on session_info_update once per host, carrying the pinned and served schema fingerprints and the detected host version; a mismatch is advisory and never blocks a session.

Clients can opt into muse/sessionState to receive observed host model and approval-mode changes, plus verified or explicitly unverified persistent-rule outcomes. These reports do not change ACP configuration or permission policy. See observed session state.

Approval and sandbox controls

SDK bypassApprovals automatically selects only host-offered once approvals at all stages, with no ACP dialogs or persistent grants. rejectApprovals rejects pending prompts using offered once-denial choices; known-safe tools can still run. Both work on Muse 1.1.1 and 1.2.1. Select them using either session/set_mode or session/set_config_option with configId: "mode".

Separate SDK config options select nativeApprovalPolicy, sandbox, sandboxNetwork, workspaceWrite and shell. Defaults remain prompted onRequest, sandbox enabled, proxy-only network, writes and shell enabled. Non-default native policies require Muse 1.2.1+; automatic once decisions work on 1.1.1 without those policies. Disabling the sandbox additionally requires MUSE_CODE_ACP_ALLOW_YOLO=1. No SDK option implicitly trusts workspace rules.

Changes require an idle session and replace its retained host. Load/resume restore validated preferences; fork resets safety settings and modes. See the policy matrix and platform limits.

Legacy exec backend (rollback)

MUSE_CODE_ACP_BACKEND=exec muse-code-acp

The legacy backend runs muse exec --json per turn. It supports the echo provider, uses store-based session listing and accepts stdio MCP servers only. Approvals resolve inside Muse rather than through interactive ACP permissions. Default, read-only and bypass-approvals modes are available; advertising yolo requires MUSE_CODE_ACP_ALLOW_YOLO=1.

SDK failures never silently switch to exec. The legacy backend was introduced for Muse 0.2.1; this release's integration baseline remains 1.1.1-R2514.1.

🧩 Compatibility

Piece	Verified / required
Node.js	22+ (npm install)
Muse host	1.1.1-R2514.1 baseline (muse serve); select via MUSE_CODE_EXECUTABLE
Also verified	1.2.1-R2847.1 (session load/resume, multi-stage allow/deny, HTTP MCP); CI also runs 1.4.14-R7309.1
Muse SDK	@muse-code/sdk@1.4.13 (pinned dependency; does not include the Muse binary)
Newer-host features	Native goals 1.4.6+; /recap, skills import, plugins/hooks 1.4.7+; /compact 1.4.12+
Auth	Browser login or META_API_KEY

Keep the default SDK backend when sessions must stay resumable on hosts before 1.4.6 — see the :auto-review note below. Don't point MUSE_CODE_EXECUTABLE at an old launcher cache (the launcher removes superseded binaries); keep the verified binary at a separate path. CI's public 1.1.1 artifacts, exact macOS ARM64/Linux URLs, and SHA-256 checks are in CI.

Full compatibility history (1.2.1 – 1.4.6, :auto-review, exec stalls)

The supported baseline remains Muse 1.1.1-R2514.1 (verified host for adapter 0.5.x). Adapter 0.5.0 also verifies SDK-created session load/resume, multi-stage allow/deny, and HTTP MCP tool calls and startup failures on 1.2.1-R2847.1. ACP-provided MCP servers explicitly use required startup mode; authentication, malformed responses and unreachable endpoints fail the prompt.

One host limitation remains on 1.2.1, 1.3.0, 1.4.3 and 1.4.4: legacy muse exec sessions saved with :auto-review cannot be resumed in muse serve, whose automated reviewer is unavailable. From 1.3.0-R3401.1 the host also refuses to read them, so ACP session/load fails with the same message instead of replaying history. From 1.4.3 muse exec saves new sessions with :auto-review by default, so new sessions from the opt-in exec backend are affected too. From 1.4.4, exec-backend Read-only and Plan sessions use Muse's built-in :read-only profile and stay loadable; Default mode keeps :auto-review, because the loadable alternative would run tools without approval (upstream: muse-code-sdk#80).

Muse 1.4.6 runs its automated reviewer in muse serve too, and loads and continues these sessions; on earlier hosts, keep the default SDK backend when sessions must stay resumable. On 1.4.6 the reviewer also decides SDK-backend approval requests first: low-risk calls it approves run without an ACP permission prompt, and only escalations reach the client. In exec Default mode, a tool call that Muse's reviewer escalates to a user cannot be answered headlessly; the adapter stops the run after 120 seconds (MUSE_CODE_ACP_EXEC_APPROVAL_STALL_MS) and fails the prompt with that reason instead of hanging (muse-code-sdk#99). This affects the legacy-continuation portion of three live tests; SDK-created session continuation passes. The adapter reports an actionable error and does not replay the prompt or change the saved permission profile. Start a new ACP session or continue the old one in Muse with reviewer support. These fixes are included in 0.5.0.

Stored full tool output on Muse 1.2.1 is available to negotiated clients through bounded public output reads, including after session load. For slow SDK startup, configure the startup and submission deadlines. Failure responses distinguish operations that submitted no model turn from submissions with an unknown outcome.

⚙️ Configuration

Variable	Meaning
MUSE_CODE_EXECUTABLE	Path to the external Muse binary; takes precedence over PATH discovery
MUSE_CODE_ACP_BACKEND	sdk (default) or exec; unknown values fail at startup
META_API_KEY	Provider credential; takes priority over stored auth
MUSE_CODE_ACP_ALLOW_YOLO	Opt in to exec yolo or separately selected SDK sandbox-off
MUSE_AGENT_LOGS	Directory for adapter spawn/stderr logs
MUSE_CODE_ACP_STALL_MS	Stall bound for pending host requests, default 10000 (SDK backend)
MUSE_CODE_ACP_GATEWAY_URL	Explicit model gateway endpoint; requires MUSE_CODE_ACP_GATEWAY_KEY
MUSE_CODE_ACP_GATEWAY_KEY	Bearer token for that gateway; never persisted

muse-code-acp --cli login and muse-code-acp --cli logout delegate to the selected Muse executable. Logout does not unset an exported META_API_KEY.

❓ FAQ

Zed says muse-code-acp not found? Use the absolute path to the installed binary as command, and make sure Node 22+ is available to the editor process (GUI apps may not inherit your shell PATH).

It worked in the terminal but not in the editor? Set MUSE_CODE_EXECUTABLE (and META_API_KEY if you use it) inside the editor's agent env, not only in your shell.

Which Muse version should I actually run? Pin 1.1.1-R2514.1 unless you need a documented newer-host feature. Check with "$MUSE_CODE_EXECUTABLE" --version. Newer hosts are verified for specific surfaces — see Compatibility.

Headless / CI auth? Provide META_API_KEY to the adapter process. Browser login inside a client needs terminal-auth support; otherwise run muse login (or muse-code-acp --cli login) beforehand.

SDK or exec backend? Stay on the default SDK backend. The exec backend is a rollback path only (stdio MCP only, approvals resolved inside Muse, :auto-review resumability caveats before 1.4.6). SDK failures never silently fall back to exec.

📖 Documentation

Start here

• Capability evidence and current ownership
• Observed usage, plans, summaries and tool output
• Failure and authentication observations — structured SDK errors, credentials, startup deadlines, recovery

Sessions & workflows

• Session discovery and metadata · Native session branching · Embedded input and local session commands
• Planning and Git reviews · Goal observation & controls · Workflow and background tasks

Protocol & internals

• SDK support, model discovery, editor context and steering
• MCP passthrough and diagnostics · File-change evidence and negotiated reports · Stored output reads
• Standalone Apple Silicon macOS builds — source build + CI verification only; prebuilt binaries are not published. These builds include Node and still require external Muse.

🛠️ Development

From a repository checkout:

npm ci
npm run check                 # eslint + prettier
npm run build                 # TypeScript compilation
npm run test:unit             # deterministic contracts; no Muse host required
npm run test:coverage         # same suite with enforced coverage thresholds
npm run test:unit:shuffle     # same suite in random order (prints its seed)
npm run test:pack-smoke       # clean tarball install and ACP execution

For real-host tests, put the verified Muse binary on PATH as muse, set MUSE_CODE_EXECUTABLE to it, build first, then:

MUSE_CODE_ACP_REQUIRE_MUSE=1 npm run test:muse-loopback

These tests use a local loopback provider and are required in CI; the flag prevents a missing host from silently skipping acceptance. Suites for newer host features (e.g. native goal controls from Muse 1.4.6) skip on older hosts — set MUSE_CODE_ACP_REQUIRE_HOST_FEATURES=all, or a comma-separated list such as goal-controls,session-commands, to make those skips fail. CI runs the loopback suites on the 1.1.1-R2514.1 baseline and on 1.4.14-R7309.1 with every capability required. npm run test:run builds and runs the full local Vitest suite; paid-provider tests are opt-in via npm run test:integration and require credentials.

The work board lives in .pm/. Repository skills for release, PM, and workstream execution, Bex QA live in .agents/skills/. npm publishing runs through GitHub Actions after CI validates the exact release commit.

⭐ Support the project

• Star the repo if muse-code-acp got Muse into your editor — it's the cheapest way to help other developers find it.
• File issues with evidence: editor/client, muse --version, adapter version, backend (sdk/exec), and the failing command or session flow.
• Contribute carefully: run npm run check && npm run build && npm run test:unit before sending changes, and keep capability claims backed by tests or docs/ evidence.

License

Apache-2.0. Portions derived from claude-agent-acp (Zed Industries) — see NOTICE.