xonecas.io
64875
Mc

mini-coder / commit 94391d2

docs: consolidate into single manual, refresh README and skill

- Delete docs/configs.md, custom-agents.md, custom-commands.md, skills.md
- Rewrite docs/mini-coder.1.md as consolidated man-page-style manual
- Rewrite README.md to be shorter and more scannable
- Add /login command to mini-coder-idea.md
- Add /login, /logout, and mc-edit docs to SKILL.md

xonecas2026-03-16 94391d26fd07c58a4dd4dacae08528fdf5dec7f4 parent b35e1eb

8 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.agents/skills/mini-coder/SKILL.md+41−0
@@ -95,6 +95,9 @@ Inside `mc`, the user can run slash commands such as:
9595 - `/mcp add <name> stdio <cmd> [args...]` — add a stdio MCP server
9696 - `/mcp remove <name>` — remove an MCP server
9797 - `/agent [name]` — set or clear an active primary custom agent
98+- `/login` — show OAuth login status
99+- `/login <provider>` — login via OAuth (opens browser). Currently supports `anthropic`
100+- `/logout <provider>` — clear saved OAuth tokens
98101 - `/exit`, `/quit`, `/q` — leave the session
99102
100103 ## Prompt input features
@@ -115,6 +118,44 @@ mini-coder itself is shell-first: repo inspection happens primarily through shel
115118
116119 This helps users quickly pull relevant context into a prompt.
117120
121+## File editing with mc-edit
122+
123+`mc` is shell-first. The preferred workflow for file edits is: inspect with shell → edit with `mc-edit` → verify with shell.
124+
125+`mc-edit` is a helper command invoked from the shell tool for targeted, exact-text file edits:
126+
127+```sh
128+mc-edit <path> (--old <text> | --old-file <path>) [--new <text> | --new-file <path>] [--cwd <path>]
129+```
130+
131+- Applies one exact-text replacement to an existing file
132+- The old text must match exactly once (fails on zero or multiple matches)
133+- Omit `--new`/`--new-file` to delete the matched text
134+- On success: prints a unified diff + metadata (`ok`, `path`, `changed`)
135+- On no-op: prints `(no changes)` + metadata
136+- Errors go to stderr
137+
138+### Examples
139+
140+Replace a function signature:
141+
142+```sh
143+mc-edit src/auth.ts --old "function login(user)" --new "async function login(user)"
144+```
145+
146+Delete a block:
147+
148+```sh
149+mc-edit src/config.ts --old "// TODO: remove this
150+const DEBUG = true;"
151+```
152+
153+Use temp files for large edits:
154+
155+```sh
156+mc-edit src/big-file.ts --old-file /tmp/old.txt --new-file /tmp/new.txt
157+```
158+
118159 ## Config locations
119160
120161 mini-coder supports both `.agents` and `.claude` config layouts.
README.md+39−157
@@ -6,194 +6,76 @@
66
77 > _Small. Fast. Gets out of your way._
88
9-[📖 Read the Full Manual](https://sacenox.github.io/mini-coder/)
9+[📖 Read the Full Manual](docs/mini-coder.1.md)
1010
11-Hey there! I'm **mini-coder** — a CLI coding agent built for developers who want a sharp tool, not a bloated IDE plugin. Think of me as the pocket knife of AI coding assistants: lightweight, reliable, and always ready.
12-
13----
14-
15-## 🤙 Who Am I?
16-
17-I'm `mc` — your new terminal companion. I live in your shell, speak to large language models, and help you explore, understand, and modify code at the speed of thought.
18-
19-I was built with a simple philosophy: **dev flow first**. No slow startup. No clunky GUI. No vendor lock-in. Just you, your terminal, and an AI that keeps up.
11+A terminal coding agent for developers who want a sharp tool, not a bloated IDE plugin. Shell-first, multi-provider, minimal tool surface. Just you, your terminal, and an AI that keeps up.
2012
2113 ![Minicoder Preview](./assets/preview.gif)
2214
2315 ---
2416
25-## 🛠️ What Can I Do?
26-
27-My toolkit is lean on purpose — every tool earns its spot, no passengers:
28-
29-| Tool | What it does |
30-| --------------- | -------------------------------------------------------------------------- |
31-| 🐚 `shell` | Run shell commands, inspect the repo, and use `mc-edit` for targeted edits |
32-| 🤖 `subagent` | Spawn a focused mini-me for parallel subtasks |
33-| 🧰 `listSkills` | List discovered skills without loading full skill bodies |
34-| 📘 `readSkill` | Load one `SKILL.md` on demand |
35-| 🌐 `webSearch` | Search the web when `EXA_API_KEY` is set |
36-| 📄 `webContent` | Fetch full page content from URLs when `EXA_API_KEY` is set |
37-
38-mini-coder is intentionally **shell-first**: inspect with shell, edit with `mc-edit`, verify with shell.
39-
40-Need more firepower? I also connect to **MCP servers** over HTTP or stdio — attached MCP tools show up dynamically whenever the job calls for them.
41-
42----
43-
44-## ⚡ Key Features
45-
46-- **Multi-provider** — set `OPENCODE_API_KEY` for Zen, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY` or `GEMINI_API_KEY`, or just run Ollama locally (`OLLAMA_BASE_URL` optional). I auto-discover whatever's available.
47-- **Built-in web search** — set `EXA_API_KEY` and I expose `webSearch` + `webContent` tools.
48-- **Session memory** — conversations are saved in a local SQLite database. Resume where you left off with `-c` or pick a specific session with `-r <id>`.
49-- **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
50-- **Slash commands** — `/model` or `/models` to list/switch models, `/model effort <low|medium|high|xhigh|off>` for reasoning effort, `/reasoning [on|off]` to toggle reasoning display, `/context` to inspect or tune pruning/tool-result caps, `/cache` to configure prompt caching, `/review` for a code review (global custom command, auto-created at `~/.agents/commands/review.md`), `/agent [name]` to set or clear an active primary agent, `/undo` to remove the last conversation turn (it does not rev …
51-
52-- **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Claude-compatible `.claude/commands/` works too. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/` and `~/.claude/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
53-- **Custom agents** — drop a `.md` file in `.agents/agents/` or `.claude/agents/` (or `~/.agents/agents/` / `~/.claude/agents/` globally) and activate it with `/agent [name]`. Agent definitions are also exposed to subagent delegation unless `mode: primary`. → [docs/custom-agents.md](docs/custom-agents.md)
54-- **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Claude-compatible `.claude/skills/<name>/SKILL.md` works too. Skills are _never_ auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
55-- **Beautiful, minimal output** — compact tool output, formatted trees for file searches, a live status bar with model, git branch, and token counts.
56-- **16 ANSI colors only** — my output inherits _your_ terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
57-
58----
59-
60-## 🧠 Interesting Things About Me
61-
62-- **I eat my own dog food.** I was built _by_ a mini-coder agent. It's agents all the way down. 🐢
63-- **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
64-- **I respect existing conventions.** Context lives in `AGENTS.md` or `CLAUDE.md`, commands in `.agents/commands/`, agents in `.agents/agents/`, skills in `.agents/skills/` — I follow the ecosystem instead of inventing new standards.
65-- **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
66-- **I can clone myself.** The `subagent` tool lets me spin up parallel instances of myself to tackle independent subtasks simultaneously. Divide and conquer! (Up to 10 levels deep.)
67-
68----
69-
70-## 📁 Config folders
71-
72-I follow the [`.agents` convention](https://github.com/agentsmd/agents) — the shared standard across AI coding tools — and I also understand `.claude` layouts for **commands**, **skills**, and **agents**.
73-
74-| Path | What it does |
75-| -------------------------------- | ----------------------------------------------------- |
76-| `.agents/commands/*.md` | Custom slash commands (`/name`) |
77-| `.claude/commands/*.md` | Claude-compatible custom commands |
78-| `.agents/agents/*.md` | Custom agents |
79-| `.claude/agents/*.md` | Alternate `.claude` path for custom agents |
80-| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
81-| `.claude/skills/<name>/SKILL.md` | Claude-compatible skills |
82-| `.agents/AGENTS.md` | Preferred local project context |
83-| `CLAUDE.md` | Local fallback context if `.agents/AGENTS.md` is absent |
84-| `AGENTS.md` | Local fallback context if `.agents/AGENTS.md` and `CLAUDE.md` are absent |
85-| `~/.agents/AGENTS.md` | Preferred global context, prepended before local context |
86-| `~/.agents/CLAUDE.md` | Global fallback context if `~/.agents/AGENTS.md` is absent |
87-
88-Global commands, agents, and skills also work from `~/.agents/...` and `~/.claude/...`.
89-
90-For commands, skills, and agents: local overrides global, and `.agents` overrides `.claude` at the same scope. Context files are combined differently: global context is injected first, then local context. → [docs/configs.md](docs/configs.md)
91-
92----
93-
94-## 🚀 Getting Started
17+## ⚡ Quick Start
9518
96-One thing before you dive in: **I run on Bun**. You can install me via npm just fine, but [Bun](https://bun.com) still needs to be on your machine — no way around it.
19+I run on [Bun](https://bun.com) — install me via bun or npm, but Bun needs to be on your machine.
9720
9821 ```bash
99-# Install globally
100-bun add -g mini-coder
101-# or: npm install -g mini-coder
102-
103-# Set a provider key (pick one — or run Ollama locally)
104-export OPENCODE_API_KEY=your-zen-key # recommended
105-export ANTHROPIC_API_KEY=your-key # direct Anthropic
106-export OPENAI_API_KEY=your-key # direct OpenAI
107-export GOOGLE_API_KEY=your-key # direct Gemini
108-# or: export GEMINI_API_KEY=your-key
109-
110-# Optional extras
111-export OLLAMA_BASE_URL=http://localhost:11434
112-export EXA_API_KEY=your-exa-key # enables webSearch/webContent
113-
114-# Launch
115-mc
116-```
117-
118-Or drop me a prompt straight away for one-shot mode (runs once, then exits):
22+# Install
23+bun add -g mini-coder # or: npm install -g mini-coder
11924
120-```bash
121-mc "Refactor the auth module to use async/await"
122-```
25+# Set one API key (pick any)
26+export OPENCODE_API_KEY=your-key # recommended
27+export ANTHROPIC_API_KEY=your-key # direct Anthropic
28+export OPENAI_API_KEY=your-key # direct OpenAI
29+export GOOGLE_API_KEY=your-key # direct Gemini (or GEMINI_API_KEY)
12330
124-Useful flags:
31+# Optional
32+export OLLAMA_BASE_URL=http://localhost:11434 # local models
33+export EXA_API_KEY=your-key # web search tools
12534
126-```bash
127-mc -c # continue last session
128-mc -r <id> # resume a specific session
129-mc -l # list recent sessions
130-mc -m zen/claude-sonnet-4-6 # pick a model
131-mc --cwd ~/src/other-project # set working directory
132-mc -h # show help
35+# Go
36+mc
13337 ```
13438
135----
136-
137-## 🗃️ App data
138-
139-Everything I remember lives in `~/.config/mini-coder/` — here's what I'm holding onto:
39+One-shot mode: `mc "refactor auth to use async/await"` — runs once, then exits.
14040
141-- `sessions.db` — your full session history, MCP server config, and model metadata, all in one tidy SQLite file
142-- `api.log` — a request/response log for every provider call this run, if you want to peek under the hood
143-- `errors.log` — anything that went sideways, caught and written down so you can actually debug it
41+Useful flags: `-c` continue last session, `-r <id>` resume, `-l` list sessions, `-m <model>` pick a model, `-h` help.
14442
14543 ---
14644
147-## 📚 Go Deeper
45+## 🔑 OAuth Login
14846
149-The README hits the highlights — the docs have the full story:
150-
151-- [docs/custom-commands.md](docs/custom-commands.md)
152-- [docs/custom-agents.md](docs/custom-agents.md)
153-- [docs/skills.md](docs/skills.md)
154-- [docs/configs.md](docs/configs.md)
155-
156-## 🗂️ Project Structure
157-
158-```
159-src/
160- index.ts # Entry point + CLI arg parsing
161- agent/ # Main REPL loop + tool registry
162- cli/ # Input, output, slash commands, markdown rendering
163- llm-api/ # Provider factory + streaming turn logic
164- tools/ # shell, subagent, skill tools
165- # + webSearch, webContent
166- internal/ # shared internals, including the mc-edit helper implementation
167- mcp/ # MCP server connections
168- session/ # SQLite-backed session & history management
169-```
47+Use `/login` inside the REPL to authenticate via browser-based OAuth (currently Anthropic). No need to manage API keys manually.
17048
17149 ---
17250
173-## 🔮 Tech Stack
51+## 🛠️ Features
17452
175-- **Runtime:** [Bun.js](https://bun.com) — fast, modern, all-in-one
176-- **LLM routing:** [AI SDK](https://ai-sdk.dev) — multi-provider with streaming
177-- **Colors:** [yoctocolors](https://github.com/sindresorhus/yoctocolors) — tiny and terminal-theme-aware
178-- **Schema validation:** [Zod](https://zod.dev)
179-- **Linting/formatting:** [Biome](https://biomejs.dev)
180-- **Storage:** `bun:sqlite` — zero-dependency local sessions
53+- **Multi-provider** — auto-discovers Anthropic, OpenAI, Gemini, Ollama, or any OpenAI-compatible endpoint
54+- **Session memory** — SQLite-backed. Resume with `-c` or `-r <id>`
55+- **Shell integration** — `!` prefix for inline commands, `@` to reference files with tab completion
56+- **Subagents** — spawn parallel mini-coder instances for independent subtasks
57+- **Web search** — `webSearch` + `webContent` tools when `EXA_API_KEY` is set
58+- **MCP support** — connect external tool servers over HTTP or stdio
59+- **Custom commands** — drop `.md` files in `.agents/commands/` → instant `/slash` commands
60+- **Custom agents** — `.agents/agents/*.md` for specialized personas, usable as primary or via subagent
61+- **Skills** — `.agents/skills/<name>/SKILL.md`, inject with `@name`
62+- **`mc-edit`** — safe, exact-text file editing (no full-file rewrites)
63+- **16 ANSI colors** — inherits your terminal theme. Always looks right.
18164
18265 ---
18366
184-## 💬 Philosophy
67+## 📚 Getting Deeper
18568
186-> Accurate. Fast. Focused on the conversation.
69+The README is the highlight reel. For the full story — slash commands, config folders, context files, app data, and everything else:
18770
188-I believe the best tools disappear into your workflow. I don't want to be the star of the show — I want _you_ to ship great code, faster.
71+**[📖 Read the Full Manual](docs/mini-coder.1.md)**
18972
19073 ---
19174
192-## 💬 What People Are Saying
75+## 🔮 Tech Stack
19376
194-> "sean this is fucking sick"
195-> — [vpr99](https://github.com/vpr99)
77+[Bun.js](https://bun.com) · [AI SDK](https://ai-sdk.dev) · [yoctocolors](https://github.com/sindresorhus/yoctocolors)
19678
197----
79+## 📄 License
19880
199-_Built with ❤️ and a healthy obsession with terminal aesthetics._
81+MIT — [github.com/sacenox/mini-coder](https://github.com/sacenox/mini-coder)
docs/configs.md+0−118
@@ -1,118 +0,0 @@
1-# Config conventions
2-
3-mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
4-
5-Only commands, skills, agents, and context files are loaded from these roots. Hook directories are ignored.
6-
7-Discovery is not identical for every config type:
8-
9-- **Commands** and **agents** are loaded from the current working directory and the home directory only.
10-- **Skills** are loaded from the home directory plus local directories discovered by walking up from the current working directory to the git worktree root.
11-- **Context files** are only loaded from the current working directory and the home directory.
12-
13-## Supported config roots
14-
15-| Root | Purpose |
16-|---|---|
17-| `.agents/` | mini-coder native config |
18-| `.claude/` | Alternate config layout supported by mini-coder |
19-
20-Each root can exist in:
21-
22-- **Local (repo):** `./.agents`, `./.claude`
23-- **Global (home):** `~/.agents`, `~/.claude`
24-
25-## Commands
26-
27-Supported locations:
28-
29-- `./.agents/commands/*.md`
30-- `~/.agents/commands/*.md`
31-- `./.claude/commands/*.md`
32-- `~/.claude/commands/*.md`
33-
34-Format:
35-
36-```md
37----
38-description: Optional help text
39-model: optional/model-override
40----
41-
42-Prompt template body with $ARGUMENTS and $1..$9 support.
43-```
44-
45-Filename becomes the command name (`review.md` => `/review`).
46-
47-## Skills
48-
49-Supported locations:
50-
51-- local: `./.agents/skills/<skill-name>/SKILL.md` and `./.claude/skills/<skill-name>/SKILL.md`
52-- global: `~/.agents/skills/<skill-name>/SKILL.md` and `~/.claude/skills/<skill-name>/SKILL.md`
53-
54-For local skills, mini-coder searches not just the current working directory, but each ancestor directory up to the git worktree root.
55-
56-Format:
57-
58-```md
59----
60-name: required-skill-name
61-description: Required help text
62----
63-
64-Skill instructions/content.
65-```
66-
67-Both `name` and `description` are required. Invalid skills are skipped with a warning.
68-
69-## Agents
70-
71-Supported locations:
72-
73-- `./.agents/agents/*.md`
74-- `~/.agents/agents/*.md`
75-- `./.claude/agents/*.md`
76-- `~/.claude/agents/*.md`
77-
78-Format:
79-
80-```md
81----
82-description: Optional help text
83-model: optional/model-override
84-mode: optional agent mode
85----
86-
87-Agent system prompt.
88-```
89-
90-## Context files
91-
92-mini-coder loads at most one global context file and at most one local context file, then includes both when present.
93-
94-Global lookup order:
95-
96-1. `~/.agents/AGENTS.md`
97-2. `~/.agents/CLAUDE.md`
98-
99-Local lookup order:
100-
101-1. `./.agents/AGENTS.md`
102-2. `./CLAUDE.md`
103-3. `./AGENTS.md`
104-
105-Injection order:
106-
107-1. Global context (if found)
108-2. Local context (if found)
109-
110-## Precedence and conflicts
111-
112-Precedence rules for commands, skills, and agents:
113-
114-1. **Local overrides global**
115-2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
116-3. For **skills only**, when the same skill name exists in multiple local ancestor directories, the skill nearest to the current working directory wins
117-
118-When same-scope `.agents` / `.claude` conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.
docs/custom-agents.md+0−69
@@ -1,69 +0,0 @@
1-# Custom Agents
2-
3-A custom agent is a reusable system prompt with an optional model override.
4-You can activate one with `/agent <name>`, and non-`primary` agents are also exposed to the `subagent` tool.
5-
6-mini-coder is shell-first, so custom agents should assume repo inspection and verification happen through shell, with targeted edits done via `mc-edit` invoked from shell.
7-
8-## Where to put them
9-
10-| Location | Scope |
11-|---|---|
12-| `.agents/agents/*.md` | Current repo only |
13-| `~/.agents/agents/*.md` | All projects (global) |
14-| `.claude/agents/*.md` | Current repo only (`.claude` layout) |
15-| `~/.claude/agents/*.md` | All projects (global, `.claude` layout) |
16-
17-Local agents override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
18-
19-## Create an agent
20-
21-The filename becomes the agent name.
22-
23-`~/.agents/agents/reviewer.md`:
24-
25-```md
26----
27-description: Strict code reviewer focused on bugs and structure
28-model: zen/claude-sonnet-4-6
29----
30-
31-You are a senior engineer doing a code review. Be direct and specific.
32-Cite file and line number for every finding. Flag bugs first, then
33-structure issues, then style — only if they violate project conventions.
34-No flattery. End with a one-line verdict.
35-```
36-
37-Then in the REPL:
38-
39-```
40-/agent reviewer
41-review the auth module for race conditions
42-```
43-
44-## Frontmatter fields
45-
46-| Field | Required | Description |
47-|---|---|---|
48-| `description` | No | Shown in `/help`. Defaults to filename. |
49-| `model` | No | Override the active model for this agent. |
50-| `mode` | No | Controls whether the agent is exposed through the `subagent` tool. `primary` excludes it from that tool and is intended for `/agent`. `subagent`, `all`, and an omitted value all keep it available to the `subagent` tool. Any loaded agent can currently still be selected with `/agent <name>`. |
51-
52-The markdown body (after frontmatter) is the agent's system prompt.
53-
54-## Combining with files
55-
56-File references are resolved before the prompt is sent:
57-
58-```
59-/agent reviewer
60-@src/auth/session.ts check this file for issues
61-```
62-
63-## Listing agents
64-
65-```
66-/help
67-```
68-
69-Agents are listed in magenta, tagged `(local)` or `(global)`.
docs/custom-commands.md+0−141
@@ -1,141 +0,0 @@
1-# Custom Commands
2-
3-Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
4-
5-mini-coder is shell-first: when a command needs repo inspection or verification, tell it to use shell. When it needs a targeted file edit, tell it to invoke `mc-edit` from shell rather than relying on old local file-edit tools.
6-
7-## Where to put them
8-
9-| Location | Scope |
10-|---|---|
11-| `.agents/commands/*.md` | Current repo only |
12-| `~/.agents/commands/*.md` | All projects (global) |
13-| `.claude/commands/*.md` | Current repo only (Claude-compatible) |
14-| `~/.claude/commands/*.md` | All projects (global, Claude-compatible) |
15-
16-Local commands override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
17-
18-## Create a command
19-
20-Create a markdown file. The filename becomes the command name.
21-
22-`.agents/commands/standup.md`:
23-
24-```md
25----
26-description: Summarise what changed since yesterday
27-model: zen/claude-haiku-4-5
28----
29-
30-Run `!`git log --oneline --since=yesterday`` and summarise the changes
31-as a short standup update. Group by theme, skip merge commits.
32-```
33-
34-Then in the REPL:
35-
36-```
37-/standup
38-```
39-
40-## Frontmatter fields
41-
42-| Field | Required | Description |
43-|---|---|---|
44-| `description` | No | Shown in `/help`. Defaults to the command name. |
45-| `model` | No | Override the active model for this command (only applies when `context: fork`). |
46-| `context` | No | Set to `fork` to run the command as an isolated subagent; default runs inline. |
47-| `subtask` | No | Set to `true` to force subagent execution (OpenCode-compatible alias for `context: fork`). |
48-| `agent` | No | Run the command under a named agent's system prompt (only applies when `context: fork`). |
49-
50-## Arguments
51-
52-Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
53-
54-`.agents/commands/search.md`:
55-
56-```md
57----
58-description: Search the codebase for a topic
59-model: zen/claude-haiku-4-5
60----
61-
62-Search the codebase for: $ARGUMENTS
63-
64-Use shell and skill-loading tools as needed to explore thoroughly. Report all
65-relevant files, key code snippets with line numbers, and a short summary.
66-Be exhaustive but concise. No edits.
67-```
68-
69-```
70-/search session management
71-/search error handling in providers
72-```
73-
74-Positional tokens:
75-
76-```md
77----
78-description: Create a new component
79----
80-
81-Create a React component named $1 in the $2 directory.
82-Use TypeScript, include prop types and a default export.
83-```
84-
85-```
86-/component Button src/ui
87-```
88-
89-## Shell interpolation
90-
91-Use `` !`cmd` `` to inject shell output into the prompt at expansion time.
92-Commands time out after 10 seconds.
93-
94-```md
95----
96-description: Review failing tests
97----
98-
99-The following tests are currently failing:
100-
101-!`bun test 2>&1 | grep "fail\|✗" | head -20`
102-
103-Investigate the failures and suggest fixes. Read the relevant source
104-files before drawing conclusions.
105-```
106-
107-```
108-/fix-tests
109-```
110-
111-## Model override
112-
113-Specify a model in frontmatter to use a faster or cheaper model for
114-lightweight tasks regardless of what the session is currently set to.
115-
116-```md
117----
118-description: Quick symbol search
119-model: zen/claude-haiku-4-5
120----
121-
122-Find all usages of $ARGUMENTS across the codebase using shell.
123-List each occurrence with file path and line number. No explanations needed.
124-```
125-
126-Large models for deep analysis, small models for search and lookup.
127-
128-## Precedence
129-
130-Custom commands shadow built-ins. The global `/review`
131-command (auto-created at `~/.agents/commands/review.md` on first run) works
132-the same way — a local `.agents/commands/review.md` will override it.
133-
134-## Listing commands
135-
136-```
137-/help
138-```
139-
140-Custom commands are listed at the bottom under **custom commands**, tagged
141-with `(local)` or `(global)`.
docs/mini-coder.1.md+221−102
@@ -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.
docs/skills.md+0−83
@@ -1,83 +0,0 @@
1-# Skills
Cut short: this commit's diff is over 1000 lines.
mini-coder-idea.md+2−1
Cut short: this commit's diff is over 1000 lines.