Protonmatter · Aug 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ vo/
 *.wav
 !examples/**/*.wav
 examples/voice-profiles/*/out/
+.mcp.json
diff --git a/.mcp.json.example b/.mcp.json.example
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "project-her": {
+      "command": "project-her-mcp",
+      "args": ["--config", "./project-her.json"]
+    },
+    "desktop-commander": {
+      "command": "npx",
+      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
+    }
+  }
+}
diff --git a/README.md b/README.md
@@ -310,6 +310,16 @@ rollback artifact. The library exposes `PcmGate`, `candidate_record`,
 `validate_pcm_artifact`, `canonical_source_sha256`, and `promote_artifact` for
 that evidence path.
 
+## Editor and agent setup
+
+[`docs/DESKTOP_COMMANDER.md`](docs/DESKTOP_COMMANDER.md) covers attaching the
+Desktop Commander MCP server to the Claude Code CLI (local stdio) and to
+cloud-hosted sessions such as Cowork (remote relay device), and how that
+differs from Project-Her's own read-only MCP server. Copy
+[`.mcp.json.example`](.mcp.json.example) to `.mcp.json` to enable both servers
+for this repository; the live file is gitignored so the shell server stays
+opt-in per user.
+
 ## License
 
 Project-Her and VOForge source are MIT under [`LICENSE`](LICENSE). Voice audio is generated through third-party models

diff --git a/docs/DESKTOP_COMMANDER.md b/docs/DESKTOP_COMMANDER.md
@@ -0,0 +1,131 @@
+# Desktop Commander setup
+
+[Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP)
+(`@wonderwhy-er/desktop-commander`, v0.2.47 at the time of writing) is a
+general-purpose MCP server exposing terminal execution and file editing. This
+page records how to attach it to the two clients used with this repository —
+the Claude Code CLI and cloud-hosted Claude sessions such as Cowork — and where
+the boundary between them lies.
+
+It is a **companion to**, not a replacement for, the Project-Her MCP server
+documented in [`PROJECT_HER.md`](PROJECT_HER.md). The two answer different
+questions: `project-her` exposes validated, root-confined, read-only-by-default
+voice tooling; Desktop Commander exposes an unrestricted shell. Keep that
+distinction in mind when granting either one.
+
+## Which transport you need
+
+Desktop Commander ships one binary with three entry points. The subcommand you
+want depends entirely on **where the model is running**, not on which product
+badge it carries.
+
+| Client | Runs on | Transport | Command |
+|---|---|---|---|
+| Claude Code CLI (your machine) | your machine | local stdio | `claude mcp add ...` |
+| Cowork / Claude web (cloud session) | Anthropic infrastructure | remote relay device | `npx ... remote` |
+| Cowork desktop (local session) | your machine | local stdio | `claude mcp add ...` |
+
+A cloud-hosted session cannot spawn a process on your laptop, so the stdio
+config is unreachable from it. That gap is exactly what `remote` fills: it
+turns your machine into a registered device that a relay can dispatch tool
+calls to.
+
+## 1. Claude Code CLI (local stdio)
+
+```bash
+claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest
+```
+
+`--scope user` installs it for every project. Drop the flag to scope it to the
+current project only. Claude Code launches the server as a child process over
+stdio and shuts it down with the session; nothing leaves your machine.
+
+To pin Desktop Commander alongside `project-her` for **this** repository, copy
+the checked-in template:
+
+```bash
+cp .mcp.json.example .mcp.json
+```
+
+`.mcp.json` is deliberately **not** committed. A checked-in `.mcp.json` would
+prompt every person who clones this repository to enable an unrestricted shell
+server, which contradicts the consent-and-confirmation posture the rest of
+Project-Her is built on. Opting in is left to each user. Adjust the
+`--config` path in the copy to point at your own `project-her.json`.
+
+## 2. Cowork and Claude web (remote relay device)
+
+```bash
+npx @wonderwhy-er/desktop-commander@latest remote
+```
+
+Run this **on the machine you want the model to reach** — your own desktop.
+The flow, as implemented in `dist/remote-device/`:
+
+1. An OAuth 2.0 device-authorization flow starts (PKCE, `S256` challenge). The
+   CLI prints a verification URL and a short user code, and tries to open your
+   browser.
+2. You approve the device in the browser; the CLI polls until authorization
+   lands and a device ID is assigned.
+3. The process holds an authenticated channel to `https://mcp.desktopcommander.app`
+   and prints `✅ Device ready` with your account email, device ID, and device
+   name.
+4. Tool calls arriving over that channel execute locally under your user
+   account, and results are returned to the model.
+
+Then add Desktop Commander as a connector in your client, following the pairing
+flow at [mcp.desktopcommander.app](https://mcp.desktopcommander.app). The
+connector-registration step lives in Anthropic's client UI and the vendor's
+onboarding, not in this repository — follow whatever those present.
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `--persist-session` | Saves the session so restarts skip re-authorization |
+| `--disable-no-sleep` | Skips `caffeinate` (macOS only; otherwise the process keeps the Mac awake while connected) |
+| `--debug` | Enables verbose `console.debug` output, which is suppressed by default |
+
+### Operational boundary
+
+- The relay only works **while the process runs**. `Ctrl+C` ends access; there
+  is no background daemon left behind.
+- Commands run with your full user permissions. There is no per-tool
+  confirmation gate equivalent to the `{"confirm": true}` requirement that
+  Project-Her's render tool enforces.
+- Traffic egresses to a third-party relay (`mcp.desktopcommander.app`). That is
+  a different trust boundary from the local stdio setup in section 1, and from
+  Project-Her's stdio-only, no-network MCP server. Prefer section 1 whenever
+  the model is already running locally.
+
+## 3. What this does *not* apply to
+
+Claude Code sessions running in a **remote/web execution container** — the
+ephemeral cloud sandbox used by Claude Code on the web — should not use either
+path:
+
+- The container already grants the agent shell and file access through its
+  native tools, so a local stdio Desktop Commander is redundant.
+- Running `remote` inside the container would register the **throwaway
+  sandbox** as the device, not your desktop, and the pairing dies with the
+  container.
+
+Set Desktop Commander up on the machine you actually want reached.
+
+## Uninstalling
+
+```bash
+npx @wonderwhy-er/desktop-commander@latest remove
+```
+
+This backs up the Claude configuration before editing it and removes the
+`desktop-commander` entry. For the Claude Code CLI, `claude mcp remove
+desktop-commander` is the direct equivalent. A `.mcp.json` you copied from the
+template is removed by deleting the file.
+
+## References
+
+- Desktop Commander: <https://github.com/wonderwhy-er/DesktopCommanderMCP>
+- Remote MCP service: <https://mcp.desktopcommander.app>
+- Claude Code MCP documentation: <https://docs.anthropic.com/en/docs/claude-code/mcp>
+- Project-Her MCP server: [`PROJECT_HER.md`](PROJECT_HER.md)
diff --git a/docs/PROJECT_HER.md b/docs/PROJECT_HER.md
@@ -153,6 +153,12 @@ remain visible to a human:
 - <https://modelcontextprotocol.io/specification/2025-06-18/basic/transports>
 - <https://modelcontextprotocol.io/specification/2025-06-18/server/tools>
 
+To attach this server to a client alongside the general-purpose Desktop
+Commander shell server, see [`DESKTOP_COMMANDER.md`](DESKTOP_COMMANDER.md).
+Desktop Commander is an unrestricted terminal and file-editing server and does
+not inherit any of the root confinement, render gating, or confirmation
+controls described above.
+
 ## License matrix
 
 | Component | Governing boundary |