@@ -1,156 +1,275 @@
11 # MINI-CODER(1)
22
33 ## NAME
4-**mini-coder** (executable: `mc`) - A small, fast CLI coding agent built for developers.
4+
5+**mini-coder** — a small, fast CLI coding agent (executable: `mc`)
56
67 ## SYNOPSIS
7-`mc [options] [prompt]`
8+
9+`mc` \[*options*\] \[*prompt*\]
810
911 ## DESCRIPTION
10-**mini-coder** is a developer-focused CLI coding agent. It prioritizes developer flow with no slow startup, no clunky GUI, and no vendor lock-in. It uses a minimalist terminal UI restricted to 16 ANSI colors to inherit the user's terminal theme, and is built entirely on Bun.js for maximum performance.
12+
13+Developer-focused CLI coding agent. Prioritizes dev flow — no slow startup, no GUI, no vendor lock-in. Uses 16 ANSI colors to inherit terminal theme. Built on Bun.js.
1114
1215 ## OPTIONS
13-**-m, --model <id>**
14-: Specify the model to use (e.g., `zen/claude-sonnet-4-6`).
1516
16-**-c, --continue**
17-: Continue the most recent session.
17+`-m`, `--model` *id*
18+: Model to use (e.g. `zen/claude-sonnet-4-6`).
19+
20+`-c`, `--continue`
21+: Continue most recent session.
1822
19-**-r, --resume <id>**
20-: Resume a specific session by its ID.
23+`-r`, `--resume` *id*
24+: Resume a specific session.
2125
22-**-l, --list**
23-: List recent sessions.
26+`-l`, `--list`
27+: List recent sessions.
2428
25-**--cwd <path>**
26-: Set the working directory (defaults to current directory).
29+`--cwd` *path*
30+: Set working directory.
2731
28-**-h, --help**
29-: Display help information.
32+`-h`, `--help`
33+: Display help.
3034
31-**[prompt]**
32-: Optional one-shot prompt text. Runs once, then exits.
35+*prompt*
36+: Optional one-shot prompt. Runs once then exits.
3337
3438 ## INTERACTIVE COMMANDS
35-Inside the interactive session, the following slash commands are available:
3639
37-**/model**
38-: List all available models, indicating free models and context sizes.
40+`/model`
41+: List all available models.
3942
40-**/model <id>**
41-: Switch to a specific model.
43+`/model` *id*
44+: Switch model.
4245
43-**/model effort <low|medium|high|xhigh|off>**
44-: Configure reasoning effort levels for models that support it.
46+`/model effort` *low|medium|high|xhigh|off*
47+: Set reasoning effort.
4548
46-**/reasoning [on|off]**
47-: Toggle the display of the model's reasoning/thought process.
49+`/reasoning` \[*on|off*\]
50+: Toggle reasoning display.
4851
49-**/context prune <off|balanced|aggressive>**
50-: Configure context window pruning strategies.
52+`/context prune` *off|balanced|aggressive*
53+: Pruning strategy.
5154
52-**/context cap <off|bytes|kb>**
53-: Set a hard payload cap size for tool results to avoid blowing out context.
55+`/context cap` *off|bytes|kb*
56+: Tool result payload cap.
5457
55-**/cache <on|off>**
56-: Toggle prompt caching globally.
58+`/cache` *on|off*
59+: Toggle prompt caching globally.
5760
58-**/cache openai <in_memory|24h>**
59-: Set OpenAI prompt cache retention policies.
61+`/cache openai` *in_memory|24h*
62+: OpenAI cache retention.
6063
61-**/cache gemini <off|cachedContents/...>**
62-: Attach Google Gemini cached content.
64+`/cache gemini` *off|cachedContents/...*
65+: Gemini cached content.
6366
64-**/undo**
65-: Remove the last conversation turn. This does not revert filesystem changes.
67+`/undo`
68+: Remove last turn (does NOT revert filesystem).
6669
67-**/new**
68-: Clear context and start a fresh session.
70+`/new`
71+: Start a fresh session.
6972
70-**/mcp list**
71-: List configured MCP servers.
73+`/verbose`
74+: Toggle output truncation.
7275
73-**/mcp add <name> http <url>**
74-: Add an MCP server over HTTP.
76+`/mcp list`
77+: List MCP servers.
7578
76-**/mcp add <name> stdio <cmd> [args...]**
77-: Add an MCP server over stdio.
79+`/mcp add` *name* `http` *url*
80+: Add HTTP MCP server.
7881
79-**/mcp remove <name>** (or **rm**)
80-: Remove an MCP server.
82+`/mcp add` *name* `stdio` *cmd* \[*args...*\]
83+: Add stdio MCP server.
8184
82-**/agent [name]**
83-: Set or clear an active primary custom agent.
85+`/mcp remove` *name*
86+: Remove MCP server.
8487
85-**/review**
86-: Custom command that reviews the current session's changes (defined via `.agents/commands/`).
88+`/agent` \[*name*\]
89+: Set or clear active primary agent.
8790
91+`/review`
92+: Review changes (custom command, auto-created globally).
8893
89-**/help**
90-: Display command help.
94+`/login`
95+: Show OAuth login status.
9196
92-**/exit, /quit, /q**
93-: Leave the session.
97+`/login` *provider*
98+: Login via OAuth (opens browser for device flow). Currently supports `anthropic`.
99+
100+`/logout` *provider*
101+: Clear saved OAuth tokens.
102+
103+`/help`
104+: Command help.
105+
106+`/exit`, `/quit`, `/q`
107+: Leave session.
94108
95109 ## INLINE FEATURES
96-**Shell Integration**
97-: Prefix user prompts with `!` to run shell commands inline directly into the context.
98110
99-**File & Skill Referencing**
100-: Prefix words with `@` to reference files or skills within prompts (supports tab completion).
111+`!` prefix
112+: Runs shell commands inline.
113+
114+`@` prefix
115+: References files or skills (with tab completion).
101116
102117 ## BUILT-IN TOOLS
103-The agent has access to the following tools:
104-* **shell**: Execute bash commands and capture output. Repo inspection and targeted file edits are typically done here via `mc-edit`.
105-* **subagent**: Spawn a focused mini-agent with a prompt.
106-* **listSkills**: List discovered skills without loading full skill bodies.
107-* **readSkill**: Load one `SKILL.md` on demand.
108-* **webSearch**: Search the internet (requires EXA key).
109-* **webContent**: Fetch full page content from a URL (requires EXA key).
110-* **MCP tools**: Connected external tools attached dynamically from configured MCP servers.
111-
112-## FILE EDIT HELPER
113-**mc-edit**
114-: Helper command used from shell for one exact-text edit on an existing file. On success it prints a human-readable plain unified diff to stdout followed by a short metadata block (`ok`, `path`, `changed`). If the edit is a no-op, it prints `(no changes)` plus the same metadata. Errors are written to stderr.
115118
116-## ENVIRONMENT
117-**OPENCODE_API_KEY**
118-: OpenCode Zen API key (Recommended provider).
119+**shell**
120+: Execute bash commands; repo inspection and `mc-edit` edits happen here.
121+
122+**subagent**
123+: Spawn a focused mini-agent for parallel subtasks.
124+
125+**listSkills**
126+: List discovered skills (metadata only).
127+
128+**readSkill**
129+: Load one SKILL.md on demand.
130+
131+**webSearch**
132+: Search the web (requires `EXA_API_KEY`).
133+
134+**webContent**
135+: Fetch page content (requires `EXA_API_KEY`).
136+
137+MCP tools are connected dynamically from configured MCP servers.
138+
139+## FILE EDITING — mc-edit
140+
141+`mc-edit` is the helper for targeted file edits, invoked from **shell**.
142+
143+```
144+mc-edit <path> (--old <text> | --old-file <path>) [--new <text> | --new-file <path>] [--cwd <path>]
145+```
146+
147+- Applies one exact-text edit to an existing file.
148+- The old text must match exactly once.
149+- Omit `--new`/`--new-file` to delete the matched text.
150+- Success: prints unified diff + metadata (`ok`, `path`, `changed`).
151+- No-op: prints `(no changes)` + metadata.
152+- Errors go to stderr.
153+
154+Workflow: inspect with **shell** → edit with **mc-edit** → verify with **shell**.
155+
156+## CUSTOM COMMANDS
157+
158+Drop a `.md` file in `.agents/commands/` (local) or `~/.agents/commands/` (global) and it becomes a `/command`. Filename equals command name (`standup.md` → `/standup`).
159+
160+`.claude/commands/*.md` is also supported.
161+
162+**Frontmatter fields:**
163+
164+`description`
165+: Shown in `/help`.
166+
167+`model`
168+: Override model (only with `context: fork`).
169+
170+`context`
171+: `fork` to run as isolated subagent; default is inline.
172+
173+`subtask`
174+: `true` forces subagent (OpenCode-compatible alias).
175+
176+`agent`
177+: Run under named agent's system prompt (only with `context: fork`).
178+
179+**Argument substitution:**
119180
120-**ANTHROPIC_API_KEY**
121-: Direct Anthropic API key.
181+`$ARGUMENTS` expands to the full argument string; `$1`–`$9` expand to positional tokens.
182+
183+**Shell interpolation:**
184+
185+`` !`cmd` `` injects shell output at expansion time (10 s timeout).
186+
187+**Precedence:** custom commands shadow built-ins. Local overrides global.
188+
189+## CUSTOM AGENTS
190+
191+Drop a `.md` file in `.agents/agents/` (local) or `~/.agents/agents/` (global). Filename equals agent name. Activate with `/agent <name>`.
192+
193+`.claude/agents/*.md` is also supported.
194+
195+**Frontmatter fields:**
196+
197+`description`
198+: Shown in `/help`.
199+
200+`model`
201+: Override active model.
202+
203+`mode`
204+: `primary` excludes from subagent tool; `subagent`/`all`/omitted keeps it available.
205+
206+Body is the agent system prompt. Non-primary agents are exposed to the **subagent** tool for delegation.
207+
208+## SKILLS
209+
210+Skills are reusable instruction files at `.agents/skills/<name>/SKILL.md`.
211+
212+`.claude/skills/<name>/SKILL.md` is also supported.
213+
214+**Frontmatter (both required):**
215+
216+`name`
217+: Lowercase alphanumeric + hyphens, 1–64 chars.
218+
219+`description`
220+: Help text.
221+
222+Skills are never auto-loaded. Load explicitly:
223+
224+- `@skill-name` in prompts (injects body wrapped in `<skill>` XML).
225+- **listSkills** / **readSkill** tools at runtime.
226+
227+Local discovery walks up from cwd to the git worktree root.
228+
229+## CONFIGURATION
230+
231+Supports `.agents` and `.claude` layouts for commands, skills, agents, and context.
232+
233+Config roots: `.agents/`, `.claude/` — local (repo) or global (`~/`).
234+
235+**Context files** (one global + one local loaded):
236+
237+- Global: `~/.agents/AGENTS.md` → `~/.agents/CLAUDE.md`
238+- Local: `./.agents/AGENTS.md` → `./CLAUDE.md` → `./AGENTS.md`
239+
240+**Precedence:**
241+
242+1. Local overrides global.
243+2. Same scope: `.agents` wins over `.claude`.
244+3. Skills: nearest ancestor directory wins.
245+
246+## ENVIRONMENT
122247
123-**OPENAI_API_KEY**
124-: Direct OpenAI API key.
248+`OPENCODE_API_KEY`
249+: OpenCode Zen (recommended).
125250
126-**GOOGLE_API_KEY** (or **GEMINI_API_KEY**)
127-: Direct Google Gemini API key.
251+`ANTHROPIC_API_KEY`
252+: Direct Anthropic.
128253
129-**OLLAMA_BASE_URL**
130-: Ollama local base URL (Defaults to `http://localhost:11434`).
254+`OPENAI_API_KEY`
255+: Direct OpenAI.
131256
132-**EXA_API_KEY**
133-: Enables built-in `webSearch` and `webContent` tools.
257+`GOOGLE_API_KEY` / `GEMINI_API_KEY`
258+: Direct Gemini.
134259
135-## FILES & DIRECTORIES
136-**~/.config/mini-coder/**
137-: Application data directory. Contains `sessions.db` (SQLite database for session history, MCP server configs, and model metadata), `api.log`, and `errors.log`.
260+`OLLAMA_BASE_URL`
261+: Ollama local (defaults to `http://localhost:11434`).
138262
139-**.agents/ or .claude/ (Local or Global in ~/)**
140-: Configuration directories for advanced features:
141- * **commands/*.md**: Custom slash commands.
142- * **agents/*.md**: Custom behavioral wrappers or subagents.
143- * **skills/<name>/SKILL.md**: Isolated context/instruction snippets.
263+`EXA_API_KEY`
264+: Enables **webSearch** / **webContent**.
144265
145-**AGENTS.md / CLAUDE.md**
146-: Auto-loaded system context files for project-specific instructions.
266+## FILES
147267
148-## CORE FEATURES & ARCHITECTURE
149-* **Multi-Provider LLM Routing**: Automatically discovers API keys to route to OpenCode (Zen), Anthropic, OpenAI, Google/Gemini, or local Ollama instances.
150-* **Session Memory**: Persists conversation history in a local SQLite database, allowing users to resume past sessions effortlessly.
151-* **Subagent Delegation**: Includes a tool to spawn parallel instances of itself to tackle independent subtasks simultaneously (up to 10 levels deep).
152-* **Model Context Protocol (MCP)**: Native support for connecting external tools via MCP servers over HTTP or stdio.
153-* **Prompt Caching**: Configurable caching behaviors for supported providers (OpenAI, Gemini).
154-* **Undo Functionality**: Remove the last conversation turn from the current session history. It does not restore filesystem changes.
268+`~/.config/mini-coder/`
269+: App data directory (sessions.db, api.log, errors.log).
155270
271+`.agents/` or `.claude/`
272+: Config directories for commands, agents, skills.
156273
274+`AGENTS.md` / `CLAUDE.md`
275+: Project context files.