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`.