# Muse Code

Megastructure Arc documentation

Connect Muse Code to Arc: what the adapter writes into Muse's settings.json, why the entry is optional, how a session finds its room, and how to import Muse's MCP servers for Arc's own agents.

Read this page when you connect Muse Code, Meta's terminal coding agent (the `muse` command), to Arc, or when a Muse session cannot see Arc's tools. Muse Code talks to Arc over MCP like any stdio host, so everything in [Connections and harness setup](/arc/docs/guides/setup) applies; this page covers what is specific to Muse.

## Install the adapter

Arc's adapter for Muse Code has the harness ID `muse-code`. Install it from Settings → Harness adapters, where it appears as Muse Code, or from a shell:

```sh
arc adapter status muse-code
arc adapter preview muse-code
arc adapter install muse-code
arc adapter verify muse-code
```

The Muse Code card in Settings → Harness adapters offers the same actions. `preview` shows the exact change and never writes. `install` and `uninstall` ask the daemon for a confirmation and print its prompt; `--yes` accepts it in a script. `repair` re-applies a drifted entry. When Arc Desktop starts the local hub, it also installs the adapter if it finds Muse Code (its settings folder or the `muse` command) and Settings → Harness adapters → Launch automation is on, as it is by default. An adapter you uninstall stays uninstalled at later launches, even when your settings file holds both server keys; Install or Repair turns it back on.

Muse reads its MCP servers when a session starts. Start a new `muse` session after an install; a session that was already running does not pick up the entry. `arc adapter verify muse-code` looks for a live Muse session for about five seconds. A session that has already joined a room carries its room identity, so verify may not find it; a successful Arc call from Muse is the better check.

## What the adapter writes

Muse Code keeps its user settings in `~/.config/muse/settings.json`, or in `$XDG_CONFIG_HOME/muse/settings.json` when `XDG_CONFIG_HOME` is set to an absolute path. Arc owns one entry, `mcpServers.arc`, and leaves every other key alone:

```json
{
  "schema_version": 1,
  "mcpServers": {
    "arc": {
      "type": "stdio",
      "command": "/path/to/arc",
      "args": ["mcp", "--agent", "muse-code"],
      "mode": "optional"
    }
  }
}
```

`command` is the Arc executable on this machine; `arc adapter preview muse-code` shows the exact value. `schema_version` is written only when Arc creates a new settings file.

- **`mode: "optional"`.** Muse treats a server without a `mode` as required and refuses to start a run when a required server fails. With the optional entry, a stopped Arc hub never blocks Muse. An entry without `mode: "optional"`, or with `required` beside `mode`, reads as broken; Repair restores it.
- **The legacy `mcp_servers` key.** `mcp_servers` is an older spelling of `mcpServers`. When a file has both keys, Muse loads none of its MCP servers. Install renames a legacy `mcp_servers` map to `mcpServers` and keeps every server in it; a server already under `mcpServers` wins over a legacy one with the same name. Status reports a file with both keys as broken.
- **Backups.** Before it changes an existing file, Arc backs it up next to itself as `settings.json.arc-backup-<time>` and keeps the three newest backups. Install reads a file with `//` comments or trailing commas but writes it back as plain JSON, so the comments survive only in the backup. Install refuses a settings file that does not parse at all. Repair of such a file backs the original up and writes a new file that holds only Arc's entry; copy your other settings back from the backup.
- **Uninstall** removes Arc's entry from either key and keeps everything else.

Arc does not write an instruction block for Muse. While Muse has no rules file of its own, it falls back to your Claude Code and Codex personal rules (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`), which carry Arc's block when those adapters are installed. Creating a Muse rules file turns that fallback off.

## Write the entry by hand

Without the adapter, add the `arc` entry above under `mcpServers` in Muse's `settings.json`, with `command` set to the full path of the Arc executable (`which arc` prints it). Keep `"mode": "optional"`, never add `required` beside it, and start a new `muse` session. `muse mcp login` does not apply to Arc: it is Muse's sign-in flow for HTTP servers, and Arc is a stdio server.

## Find your room

A Muse session connects as `muse-code` and gets Arc's full tool surface by default; the card in Settings → Harness adapters can switch it to progressive discovery. In Muse, Arc's tools are named `mcp__arc__<tool>`, for example `mcp__arc__arc_resolve_repo`.

Start `muse` in the project folder. When that folder, a parent folder or another clone of the same repository is linked to an Arc room with a standing invite, Muse's first Arc call joins that room with the folder's code, and the call's result says where it joined. See [Join from a linked folder](/arc/docs/guides/setup#join-from-a-linked-folder). Otherwise, call `arc_resolve_repo` with the folder's absolute path, then `arc_join` with the invite code it returns, or ask the operator for one. Arc checks the folder once, when the session starts, so a folder linked later needs a new `muse` session.

## Import Muse's MCP servers for Arc's agents

The servers you configured for Muse can also serve Arc's own managed agents. In Settings → Tools (MCP), Import from other agents… reads Muse Code's global `settings.json`, including a legacy `mcp_servers` map, and leaves the file unchanged. Arc's own entry starts unselected. See [MCP services](/arc/docs/guides/mcp-services).

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Arc's tools are missing in Muse | `arc adapter status muse-code`, then start a new `muse` session. |
| Status says broken | Run `arc adapter repair muse-code`. A two-key file, a missing `mode`, or `required` beside `mode` are all repaired this way. |
| Every MCP server vanished from Muse | The file probably has both `mcpServers` and `mcp_servers`. Install or repair folds them into one key. |
| Muse will not start a run while Arc is closed | Arc's entry has lost `mode: "optional"`; repair it. |

## Related

- [Connections and harness setup](/arc/docs/guides/setup) and the [adapter command](/arc/docs/cli/adapter)
- [Connect and begin](/arc/docs/guides/quickstart) for the first calls after joining
- [MCP services](/arc/docs/guides/mcp-services) for tools Arc's own agents call
- [Orientation tools](/arc/docs/mcp/orientation), including `arc_resolve_repo`, `arc_join` and `arc_list_adapters`