---
audience: agent-operator
publication: agent-reference
stable_id: aiwg.agent-reference.provider.muse
---

# Muse Code Operational Reference

> **AIWG provider status:** Stable (`muse`). Promoted under
> [#231](https://github.com/jmagly/aiwg/issues/231) with Linux PUW and path
> security review; maintainer guidance on 2026-10-02 waived macOS/Windows PUW.
> No aliases are registered: `muse-spark`, `muse-code`, `spark`, and `meta`
> are all deliberately rejected as provider ids. Decision record:
> [`docs/architecture/adr-muse-provider-target.md`](../../architecture/adr-muse-provider-target.md).
>
> **First time using AIWG?** Begin with
> [Install, Connect, and Verify](https://docs.aiwg.io/pages/getting-started--install-connect-verify.html).
> This guide assumes AIWG is already installed.

Deploy AIWG into **Muse Code** (Meta's terminal/CI coding agent built on Muse
Spark). This provider is **not** Cursor IDE: Muse fleets must use `--provider
muse`; Cursor IDE fleets stay on `cursor`. Overloading `--provider cursor` for
Muse deploys into paths Muse does not load and prints foreign reload guidance.

## Architecture

| Artifact | Where it lands | Notes |
| -------- | -------------- | ----- |
| Context bridge | `<project>/AGENTS.md` + `WORKSPACE.md` + `.aiwg/AIWG.md` | Trust-gated discover-first bridge |
| Agents / commands / rules | AIWG index | `aiwg discover` / `aiwg show` — no native file surface in this wave |
| Skills (kernel, project) | `<project>/.agents/skills/` | Canonical project deployment root |
| Skills (standard, project) | `<project>/.agents/.aiwg/skills/` | Only with `--copy-all`; indexed, not startup-listed |
| Skills (user) | `$XDG_CONFIG_HOME/muse/skills` | Resolved at deploy time; default `~/.config/muse/skills` |

AIWG never writes `.cursor/**` for this provider, never invents `~/.muse` or
siblings of `muse/skills` under the XDG config home, and never silently mirrors
into `~/.agents/skills` (Muse also reads that root — a second AIWG-owned copy
would list every kernel skill twice, the Codex #766 regression).

Muse Code 1.4.0 also loads **foreign personal skills** from `~/.claude/skills`
and `~/.codex/skills` as user-scope skills. If you deploy AIWG to Claude Code
or Codex at user scope as well, those copies show up in Muse too. Pass
`--no-foreign-personal-context` to `muse`, or skip the other user-scope
deploys, to keep one copy.

## Quick start (project)

Install Muse Code, then from the project root:

```bash
aiwg use all --provider muse
```

The deployment command refreshes AIWG's shared project context and prints a
verification result. Muse loads project `AGENTS.md` only after the workspace
is explicitly trusted: **trust the workspace when prompted, then start a new
Muse session** (or re-read skills) before using the deployment. Reloading an
IDE window does not apply to Muse Code. After that, work discover-first —
`aiwg discover "<intent>"`, then `aiwg show <type> <name>` — before
improvising.

Full first-run path: [`docs/integrations/muse-quickstart.md`](../../integrations/muse-quickstart.md).

## User-scope / global skills

```bash
aiwg use all --provider muse --scope user
```

User-scope skills land in the resolved XDG user root
(`$XDG_CONFIG_HOME/muse/skills`, default `~/.config/muse/skills`). Bad XDG
metadata fails closed with remediation instead of inventing a bogus tree.
`--global` is the no-project-deploy bootstrap (stage → user deploy →
lightweight project context); it is **not** identical to `--scope user`
(additive mirror).

## Verify

```bash
aiwg status --probe --json   # Muse restart copy — never Cursor wording
aiwg doctor --provider muse
```

`aiwg doctor --provider muse` checks the labeled Muse surfaces, reports a
"Muse Code native extensions" section (the `muse` CLI version, whether
`.muse/hooks.json` holds the AIWG-managed group, and whether the user
settings register the `aiwg` MCP server), the deployed
`.agents/skills/` listing, and the context/memory firewall scan over the
muse layout (`AGENTS.md` bridge + project skill root). Muse has no native
agent surface; the Agents line reports that agents are indexed and reached
via `aiwg discover` / `aiwg show`.

## Sessions

Muse keeps one directory per session under
`$XDG_DATA_HOME/muse/sessions/YYYY/MM/DD/<session-id>/` (default
`~/.local/share/muse/sessions`), with the event log in `session.jsonl` and
CLI diagnostics in `cli-*.log`. Import a session either from an explicit
`muse export --session <id-or-session.jsonl>` document, or discover native
logs for a workspace with
`aiwg sessions discover --workspace <path> --muse-root ~/.local/share/muse/sessions`.
Native discovery needs that explicit root, matches workspaces only from
workspace facts recorded in the log, and never assumes a `~/.muse` root.
Details: [Muse sessions](../../providers/muse-sessions.md).

## Models

Model ids come from Muse's Meta provider catalog. On Muse Code 1.4.0 that is
`muse-spark-1.3` (current), `muse-spark-1.3-contributor` (catalog default),
`muse-spark-1.2`, and `muse-spark-1.2-contributor`, each with a 1,007,997-token
context window and 128,000-token output limit. Select one with
`muse exec --model <id>` or the `model` key in
`$XDG_CONFIG_HOME/muse/settings.json`; AIWG never writes that key. Reasoning
effort tiers for 1.3 are `minimal`, `low`, `medium`, `high`, `xhigh`, and
`max`. Muse records the model each run used as `run.model.configured` in the
session log.

## Hooks and MCP

Hooks execute outside Muse's sandbox, as plain shell processes on the
operator's machine, and project hooks run only after the folder is trusted.
Review `.muse/hooks.json` before trusting a workspace.

- `aiwg use --provider muse` installs one AIWG-managed `SessionStart` hook
  into `.muse/hooks.json`: a read-only drift check
  (`aiwg refresh --dry-run --quiet --provider muse > /dev/null`). Muse parses
  hook stdout as structured hook output and rejects unknown JSON keys, so the
  report is discarded and the exit status is what Muse records. Operator hook groups are preserved, the managed group is
  tracked in `.muse/.aiwg-hooks.json`, and a hand-edited `hooks.json` is
  backed up before it is rewritten. Unmanaged hooks are never installed.
- Opt out with `aiwg use --provider muse --no-hooks`, or delete the matcher
  group whose command starts with `aiwg refresh --dry-run`.
- MCP is opt-in only: `aiwg use --provider muse --mcp` merges the AIWG MCP
  server into `mcp_servers` in `$XDG_CONFIG_HOME/muse/settings.json`
  (default `~/.config/muse/settings.json`). Muse 1.4.0 starts it and exposes
  its tools as `mcp__aiwg__*`. The merge keeps a backup of the existing
  file. A default deploy never touches user settings.

## Workspace trust

Muse natively prefers `AGENTS.md` over `CLAUDE.md` at each directory level,
but project `AGENTS.md` loads only after the workspace is explicitly trusted
(first-run trust prompt). The deployed bridge states this up front: until the
workspace is trusted, the bridge does not load. Trust the workspace when
prompted, then start a new Muse session so the bridge is read. No `CLAUDE.md`
shim is deployed for this provider.
