xonecas.io
79113
Ma

mini-coding-agent / files

mini-coding-agent / README.md

12.0 KB
1# mini-coding-agent
2
3A fast, transparent, config-first terminal coding agent.
4
5## Build
6
7Requires Zig 0.17.0.
8
9    zig build
10
11A plain `zig build` is a release build, optimized for size. `-Doptimize=debug`
12builds for development. The binary lands at `zig-out/bin/mini`. `zig build run
13-- <args>` builds and runs it. Provider model metadata is embedded from
14`src/models_dev.json`; refresh it with `python3 tools/gen_models_dev.py`.
15
16## Run
17
18    mini                           # interactive TUI
19    mini -p '<prompt>'             # one turn, print the reply, exit
20    mini -c <file>                 # overlay a config file for this run
21    mini --resume <id>             # continue a past session
22
23Arguments:
24
25| Flag | Meaning |
26|---|---|
27| `-p <prompt>`, `--print <prompt>` | run one prompt non-interactively and print the assistant text |
28| `-c <file>`, `--config <file>` | read a config file after the global one; its keys win |
29| `--resume <id>`, `--resume=<id>` | continue the session with that id, or the single session it prefixes |
30| `--no-config` | ignore the config files and run on the built-in defaults |
31| `--no-session` | record nothing; nothing to resume afterwards |
32
33`-p=<prompt>`, `--print=<prompt>`, `-c=<file>`, `--config=<file>`, and
34`--resume=<id>` work too. Any other argument exits 1.
35
36`--resume` replays the recorded conversation into the context and appends to the
37same log. The TUI prints a dim `resume with: mini --resume <id>` line when it
38exits, unless `--no-session` was given.
39
40`-p` requires a model in the config. Without one it exits 1 and prints where
41the config lives. Interactive mode requires a TTY. In `-p` mode tool calls and
42tool output go to stderr, the assistant text to stdout; a failed turn exits 1.
43`SIGINT` and `SIGTERM` cancel the turn and then re-raise, so the exit status is
44the signal.
45
46A request that fails before any event reached the context is retried with an
47exponential backoff. Every retry prints a `[retry]` line to stderr, and the TUI
48shows it in the status line.
49
50## TUI commands
51
52| Command | Meaning |
53|---|---|
54| `/help` | list commands and keybindings |
55| `/new` | start a new session |
56| `/provider` | choose the provider, then its model |
57| `/model` | choose a model for the current provider |
58| `/thinking` | set the thinking level |
59
60`/provider` lists only providers whose API key is present. `/model` needs a
61configured model and asks the provider for its model list over the wire. A
62custom provider lists what it declares. Choosing a model writes `provider` and
63`model` back to the config file, then opens the thinking picker; `/thinking`
64writes `thinkingEffort`. The file written is the one `-c` named, when given.
65
66## Keybindings
67
68| Key | Meaning |
69|---|---|
70| `Enter` | submit; on an empty draft after a failure, retry it |
71| `Shift+Enter`, `Alt+Enter`, `Ctrl+J` | newline |
72| `Shift+Up`, `Shift+Down` | walk past input |
73| `Ctrl+R` | reverse search past input |
74| `Esc` | pause the turn at the next step boundary; close a picker |
75| `Ctrl+C` | cancel the turn; otherwise close a picker or clear the draft |
76| `Ctrl+D` | exit on an empty draft |
77| `Tab` | complete command or path |
78| `Ctrl+Left`, `Ctrl+Right` | move by word |
79| `Ctrl+W`, `Ctrl+Backspace`, `Alt+B` | delete the word before the cursor |
80| `Home`, `Ctrl+A` / `End`, `Ctrl+E` | line start / line end |
81| `Ctrl+Home`, `Ctrl+End` | draft start / draft end |
82| `Delete` | delete forward |
83
84While a turn is paused (`Esc`), submitting a message steers the running turn.
85
86The status line shows the phase, the elapsed time, the estimated context use
87against the model's window, and the cache-read share of the last prompt.
88
89## Tools
90
91The model sees only the tools listed in `tools`; a call to any other name is an
92error.
93
94| Tool | Behavior |
95|---|---|
96| `read` | returns a file's text; `offset` (1-based) and `range` give a line window; text is cut at 100k characters; binary files are refused; `png`/`jpg`/`jpeg`/`webp` are returned as an image only when the model accepts image input, and only if the base64 form stays under 5 MiB |
97| `edit` | replaces `oldText`, which must occur exactly once; an empty `oldText` creates a new file and fails if it exists; prints a unified diff |
98| `bash` | runs `bash -c` in the cwd with a 120s default `timeout`; output keeps the first 10k and last 6k bytes around a truncation marker and ends with an `exit code:` line; a before/after snapshot of the cwd reports changed files as diffs |
99
100Both `read` and `edit` expand a leading `~/`. Tool arguments are parsed once at
101the boundary and validated there; a bad shape fails the call with a message.
102
103The TUI renders one line per call: the tool name, a clipped preview of its
104arguments (the first line of a `bash` command, the path for `read`/`edit`), and
105the call's metadata (`exit 0 · 12 lines`). For `read` and a successful `bash`
106that metadata replaces the output; a failed call still shows its output. Calls
107are not separated by blank lines. Changed files render as diffs with
108`+added -removed` counts.
109
110## Configure
111
112The config is one JSON object. It is read from
113`$XDG_CONFIG_HOME/mini-coding-agent/config.json`, else
114`$HOME/.config/mini-coding-agent/config.json`. A missing file means every
115default. There is no project-local config. `-c` reads a second file over it.
116
117A full example:
118
119```json
120{
121  "provider": "opencode",
122  "model": "deepseek-v4.1-flash",
123  "thinkingEffort": "medium",
124  "showImages": false,
125  "systemPrompt": "Be terse.",
126  "sessionsDir": "/home/me/.local/state/mini-coding-agent/sessions",
127  "discoverAgentFiles": true,
128  "skillsDirs": ["/home/me/.agents/skills"],
129  "tools": ["edit", "read", "bash"],
130  "programStatus": false,
131  "herdr": false,
132  "notifications": "off",
133  "retries": 3,
134  "retryBaseMs": 1000,
135  "streamIdleTimeoutMs": 120000,
136  "snapshotIgnoreDirs": [".git"],
137  "snapshotUsesGitignore": true,
138  "snapshotDiffsInContext": false,
139  "historySize": 100,
140  "maxDiffLines": 2000,
141  "colorscheme": { "prompt": "#5f87ff", "err": "#ff5f5f" },
142  "customProviders": [
143    {
144      "id": "local",
145      "name": "Local",
146      "models": [
147        {
148          "id": "qwen3-coder",
149          "name": "Qwen3 Coder",
150          "api": "openai-completions",
151          "baseUrl": "http://127.0.0.1:11434/v1",
152          "context": 32768,
153          "maxOutput": 8192,
154          "images": false,
155          "reasoning": true,
156          "effort": ["low", "high"],
157          "cost": [0, 0, 0]
158        }
159      ],
160      "envKeys": ["LOCAL_API_KEY"],
161      "headers": { "x-tenant": "mini" }
162    }
163  ]
164}
165```
166
167Keys:
168
169| Key | Default | Meaning |
170|---|---|---|
171| `provider` | unset | provider id; built-ins are `opencode`, `opencode-go` and `openrouter`, or a `customProviders` id |
172| `model` | unset | model id |
173| `thinkingEffort` | unset | one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; unset sends no reasoning parameter; a level the model does not accept clamps up to the next accepted one, else down |
174| `showImages` | `false` | draw the images the `read` tool returns inline using the kitty graphics protocol; requires kitty 0.28+ |
175| `systemPrompt` | `""` | prepended to the system prompt |
176| `sessionsDir` | `$XDG_STATE_HOME/mini-coding-agent/sessions`, else `$HOME/.local/state/mini-coding-agent/sessions`, else `sessions` | where JSONL session logs go |
177| `discoverAgentFiles` | `true` | load `AGENTS.md`/`CLAUDE.md` from `$HOME/.agents` and the cwd, deduplicated by real path |
178| `skillsDirs` | `[]` | directories holding `<name>/SKILL.md` skills; each `SKILL.md` needs a `name` in its frontmatter (optional `description`) |
179| `tools` | `["edit", "read", "bash"]` | which tools the model sees |
180| `customProviders` | `[]` | in-tree provider definitions |
181| `programStatus` | `false` | report agent state to the terminal with OSC 7501 |
182| `herdr` | `false` | report agent state to a Herdr pane; only active inside one (`HERDR_ENV=1` with `HERDR_BIN_PATH` and `HERDR_PANE_ID`) |
183| `notifications` | `off` | how the TUI asks for attention when a turn completes, fails, or pauses for steering: `off`, `osc9` (desktop notification), `bell`, or `both` |
184| `retries` | `3` | retries after a failed request, when nothing has been streamed yet; transport failures, `429`, and `5xx` retry, other statuses do not |
185| `retryBaseMs` | `1000` | first backoff step; each retry doubles it, capped at 30s |
186| `streamIdleTimeoutMs` | `120000` | a stream that stays silent this long is dropped and retried; `0` disables the window |
187| `snapshotIgnoreDirs` | `[]` | directory names skipped when the `bash` tool snapshots the cwd for diffs |
188| `snapshotUsesGitignore` | `true` | also skip paths matched by the `.gitignore` files under the cwd when snapshotting |
189| `snapshotDiffsInContext` | `false` | send the `bash` tool's snapshot diffs to the model inside the tool result |
190| `historySize` | `100` | past inputs kept in `<state dir>/mini-coding-agent/history` for `Shift+Up`/`Shift+Down` and `Ctrl+R` |
191| `maxDiffLines` | `2000` | diffs longer than this render as a "too large" notice instead of highlighting every line |
192| `colorscheme` | `{}` | per-role `#rrggbb` foreground overrides; roles are `comment`, `prompt`, `accent`, `err`, `warn`, `code`, `output`, `diff_add`, `diff_delete`, `inline_code`, `link`, `uri`, `heading1`-`heading6`; a role left out keeps its terminal palette color |
193
194Unknown keys are rejected. `provider` and `model` must both be set to make a
195request; a custom provider must list the model in its `models`. Config errors
196name the file and the parser message, then exit 1. A `-c` file must exist.
197Saving rewrites the file through a `.tmp` sibling and a rename.
198
199A `customProvider` field:
200
201| Field | Required | Meaning |
202|---|---|---|
203| `id` | yes | the id `provider` selects |
204| `name` | no | display name; falls back to `id` |
205| `models` | yes | non-empty list of model objects |
206| `envKeys` | no | environment variables searched, in order, for the API key; with none the provider is always usable |
207| `headers` | no | extra request headers |
208
209A `customProvider` model object; every model carries its own wire and metadata,
210so one provider may mix APIs and base URLs:
211
212| Field | Required | Meaning |
213|---|---|---|
214| `id` | yes | the id `model` selects |
215| `name` | no | display name; falls back to `id` |
216| `api` | yes | one of `openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` |
217| `baseUrl` | yes | request base URL |
218| `context` | yes | context window in tokens |
219| `maxOutput` | yes | maximum output tokens |
220| `images` | yes | whether the model accepts image input |
221| `reasoning` | yes | whether the model reasons |
222| `effort` | no | accepted thinking levels; empty means the full ladder |
223| `cost` | yes | `[input, output, cache-read]` USD per million tokens |
224
225## Environment
226
227The built-in providers are named, keyed and described by the embedded models.dev
228document. `opencode` and `opencode-go` read the first present variable in their
229`env` list (`OPENCODE_API_KEY`), and send the session id as
230`x-opencode-session`. `openrouter` reads `OPENROUTER_API_KEY`.
231
232Each wire carries its own key header:
233
234| API | Key header | Path |
235|---|---|---|
236| `openai-completions` | `Authorization: Bearer <key>` | `/chat/completions` |
237| `openai-responses` | `Authorization: Bearer <key>` | `/responses` |
238| `anthropic-messages` | `x-api-key: <key>`, plus `anthropic-version: 2023-06-01` | `/messages` |
239| `google-generative-ai` | `x-goog-api-key: <key>` | `/{model}:streamGenerateContent?alt=sse` under `baseUrl` |
240
241All requests ask for an SSE stream. A built-in provider with no key is left out
242of `/provider`, and so is a custom one whose `envKeys` are all unset.
243
244## Sessions
245
246Each session is a directory under `sessionsDir` named
247`<timestamp>-<title>-<id>` with a `session.jsonl` inside it. The title is the
248first user message slugified to at most 40 characters, else `session`. A header
249line opens the log; every message and every model request is then appended and
250fsynced. The log is write-only; a write failure stops the turn. `/new` closes
251the current log and opens the next one.
252
253A failed model request is never appended: the attempt stays a request line with
254no message, so the context holds no error and the next turn resends the same
255request instead of a `continue`.