How to use mini-me from an editor (ACP)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# How to use mini-me from an editor (ACP)

This guide shows how to host `mm` inside an editor that speaks the Agent Client Protocol, such as Zed. It assumes `mm` is built and installed on your `PATH` (`./install.sh` copies it to `/usr/local/bin`), and that your model server is running.

## Steps

1. Register `mm` as an agent server in the editor, with the `-acp` flag. In Zed, add to `settings.json`:

   ```json
   {
     "agent_servers": {
       "mini-me": {
         "type": "custom",
         "command": "mm",
         "args": ["-acp"],
         "env": { "AGENT_CONFIG": "/absolute/path/to/agent.yaml" }
       }
     }
   }
   ```

2. Point `AGENT_CONFIG` at an absolute path. The editor launches `mm` with the project's directory as working directory, so a relative `./agent.yaml` would not be found. In ACP mode a relative `skillsDir` in that file is resolved next to the file, not next to the editor's working directory.

3. Open the agent panel and start a conversation. Each `bash`, `read_file`, `write_file` and `edit_file` call appears as a tool call. By default (`yolo: true`) they run at once; with `yolo: false` in the configuration, the editor asks you to allow each `bash`, `write_file` and `edit_file` call before it runs. `read_file` and `read_skill` never ask.

4. Read the logs when something looks wrong. In ACP mode nothing human-readable goes to stdout: the banner, the warnings and a `[acp] …` trail go to stderr, which Zed shows under `dev: open acp logs`.

## Variants

- **Allow or refuse a tool for the whole session** (`yolo: false`). Pick "Allow bash for this session" or "Never allow bash in this session" in the permission dialog; the choice is remembered per tool until the session ends. See [How to confirm tool calls](confirm-tool-calls.md).
- **Cancel a running turn.** Use the editor's stop key (Escape in Zed). The agent answers the prompt with stop reason `cancelled` and keeps the commands that already ran in the history. There is no `/abort` over ACP.
- **Compress or restart the conversation.** Send `/compact` or `/new`; editors that list the agent's commands offer both in the slash-command menu. See the [slash commands reference](../reference/slash-commands.md#acp-mode).
- **Attach a file with `@`.** The editor's picker sends a `resource_link`, passed to the model as `[attached file: <path>]`; a path typed by hand as `@path` is understood the same way (see [`@path`](attach-a-file.md)). The model reads the file with its tools.
- **Reload the agent without losing the thread.** With `sessions.enabled: true` in the config file, the editor's Reload Agent (Zed) calls `session/load` and the whole conversation, tool calls included, is replayed into the thread; and the editor's history of threads lists the project's stored conversations (`session/list`), so an older one can be reopened. See [Keep sessions and resume them](keep-sessions.md).
- **See the JSON exchanged with the model.** Turn the trace on, in the config file (`trace: {enabled: true}`) or in the editor's settings (`"env": { "AGENT_CONFIG": "…", "AGENT_TRACE": "true" }` — the editor does not pass your shell's variables). The files land in `<project>/.mm/traces/`, the project being the session's `cwd`; the banner in the ACP logs says `trace: <session cwd>/.mm/traces`. See [How to see the JSON sent to the model](inspect-model-traffic.md).
- **Change the name the editor sees.** Add an `acp:` block to the config file; `name` is the identifier the editor logs, `title` the name it may display (leave `title` empty to not send one). The version sent is always the binary's, the one `mm --version` prints — check it with the `initialize` request below. See the [`acp` keys](../reference/configuration.md#acp-keys).

  ```yaml
  acp:
    name: mini-me
    title: Mini Me
  ```

- **Run from a terminal to debug the protocol.** `mm -acp` reads JSON-RPC on stdin and writes it on stdout, one message per line. For instance, to see how the agent introduces itself:

  ```bash
  (echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1}}'; sleep 2) \
    | mm -acp -config /absolute/path/to/agent.yaml 2>/dev/null | head -1
  ```

  The answer carries `"agentInfo":{"name":"bob","title":"Bob (bash-first agent)","version":"v0.1.7"}` with the default settings.

## See also

- The exact methods and capabilities exposed: [ACP reference](../reference/acp.md)
- Why the terminal and the editor share one loop: [architecture](../explanation/architecture.md)