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:

Slash commands worth trying first

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

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.

MUSE_CODE_ACP_BACKEND=exec muse-code-acp

🧩 Compatibility

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.

⚙️ Configuration

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.8-R6256.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 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.