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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
# Reference: command line
> Neutral description of the `mm` executable: flags, positional argument, environment variables, start-up output and exit codes.
## Invocation
```
mm [-config <path>] [-acp] [<path>]
```
| Element | Type | Default | Description |
|---------|------|---------|-------------|
| `-config <path>` | string | `""` | Path of the YAML configuration file. |
| `<path>` | positional | none | Same as `-config`, when `-config` is not given. A second positional argument is an error. |
| `-acp` | bool | `false` | Serve the Agent Client Protocol on stdin/stdout instead of the terminal REPL. |
| `-tui` | bool | `false` | Open the single-window mode (conversation above, input box below). Same effect as `tui: true` in the YAML; ignored with `-acp`. Falls back to the line mode when stdin or stdout is not a terminal. |
| `-h` | — | — | Print the flag usage and exit. |
## Configuration file resolution
The first existing source wins.
| Order | Source | Missing file |
|-------|--------|--------------|
| 1 | `-config` flag or positional argument | Error, exit code 1 |
| 2 | `AGENT_CONFIG` environment variable | Error, exit code 1 |
| 3 | `./agent.yaml` | Not an error: built-in defaults are used, the banner shows `config: built-in defaults` |
## Environment variables
| Variable | Effect |
|----------|--------|
| `AGENT_CONFIG` | Path of the configuration file (see above). |
| `AGENT_PROVIDER` | Overrides the `provider` key. |
| `AGENT_MODEL` | Overrides the `model` key. |
| `AGENT_BASE_URL` | Overrides `baseUrl` and disables the fallback probe. |
| `DMR_BASE_URL` | Same as `AGENT_BASE_URL`, for the `dmr` provider only; `AGENT_BASE_URL` wins when both are set. |
| Variable named by `apiKeyEnv` | Holds the API key. Default name: none for `dmr`, `LLAMA_API_KEY` for `llamacpp`. |
## Start-up output
Printed on stdout in terminal mode, on stderr in ACP mode. Dimmed when stdout is a terminal.
| Line | Content |
|------|---------|
| `[warning: …]` | Zero or more probe warnings: server unreachable, model not in the server's list, no chat template, compression that can never trigger. |
| `config: … \| provider: … \| model: … \| ctx: … \| tools: … \| skills: N` | Configuration path, provider name, model identifier, context window with its origin (`config`, `/props`) or `unknown`, declared tool names, number of skills found. |
| `Agent ready. Commands: …` | Terminal mode only. |
| `Shortcut: Ctrl+C …` | Terminal mode only. |
| `sessions: saved under <dir>[ · N earlier — /resume to continue the latest, /sessions to list]` | Terminal mode, `sessions.enabled` only: the resolved sessions directory and how many sessions it already holds. |
### Example
```
[warning: llamacpp: nothing answers at http://127.0.0.1:8080/v1 — start it: llama-server -m <model.gguf> --jinja --port 8080]
config: agent.llamacpp.yaml | provider: llamacpp | model: jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | ctx: unknown | tools: bash, read_file, write_file, edit_file | skills: 0
```
## ACP mode specifics
| Aspect | Behaviour |
|--------|-----------|
| stdout | JSON-RPC 2.0 messages only, one per line. |
| stderr | Banner, warnings, `[acp] …` trail, SDK logs. |
| Spinner | Disabled. |
| Relative `skillsDir` | Resolved relative to the directory of the configuration file, when a file was found; otherwise from the working directory, as in terminal mode. |
## Window mode specifics
| Aspect | Behaviour |
|--------|-----------|
| Selection | `-tui` flag, or `tui: true` in the YAML; `-acp` wins over both. |
| Terminal check | Both stdin and stdout must be character devices. Otherwise `[tui: stdin or stdout is not a terminal — running the line mode]` is printed and the line mode runs, banner included. |
| Screen | The terminal's alternate screen, released on exit; the terminal's own scrollback is not written to. |
| Banner | Not printed on stdout; shown as the first line of the conversation. |
| Spinner | Disabled; the rule under the conversation animates instead. |
| Layout | Header line (agent, model `@` provider, context use as `ctx N% (used/window)` or `ctx ~used (window unknown)`, `session <id>` when sessions are on); conversation with a scroll bar; rule with state and key hints; 3-row input box; status bar (`F1 help · Esc cancel · Ctrl-L clear · Ctrl-C quit`, `N msgs · N tools`). |
| Tool calls | `‣ <tool> <detail> <status> <time>` where status is `… pending`, `… waiting for permission`, `… running`, `✓ done` or `✗ failed`; output folded to `previewLines` lines (`… N more line(s)`); `+`/`-` lines of `write_file`/`edit_file` output coloured. |
| Errors | One line `[error: <explanation>]`; a cancelled turn shows `🛑 Generation aborted.`; each turn ends with `⚙ N command(s) [· 📝 N file op(s)] [· 📖 N skill(s)]`. |
| Permissions | With `permissions: ask`, the box shows `? <tool title>` with `[a] allow once [s] allow <tool> for this session [r] reject` until answered; a turn cancelled while asking rejects. |
| Keys | See [Slash commands — window keys](slash-commands.md#window-mode-keys). |
| Mouse | Not captured at start-up, so the terminal's click-and-drag selection works. `F2` captures it (wheel scrolling; `Shift`+drag selects) and releases it again. |
## Exit codes
| Code | Cause |
|------|-------|
| 0 | `/quit`, `Ctrl+C` at the prompt, end of stdin, or the ACP client closed the connection. |
| 1 | More than one positional argument; configuration load error; engine initialisation error (unknown provider, required key not set). |
## Build and install
| Command | Effect |
|---------|--------|
| `go build -o mm .` | Builds the binary in the current directory. |
| `./install.sh` | Builds `mm` and copies it to `/usr/local/bin`, with `sudo` when the directory is not writable. |
| `go test ./...` | Runs the unit tests. |
|
