@@ -4,7 +4,7 @@
44
55 # 👾 mini-coder
66
7-> *Small. Fast. Gets out of your way.*
7+> _Small. Fast. Gets out of your way._
88
99 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.
1010
@@ -31,41 +31,44 @@ $ mc
3131
3232 ## 🛠️ What Can I Do?
3333
34-I come equipped with a tight, reliable set of tools:
34+My toolkit is lean on purpose — every tool earns its spot, no passengers:
3535
36-| Tool | What it does |
37-|---|---|
38-| 🔍 `glob` | Find files by pattern across your project |
39-| 🧲 `grep` | Search file contents with regex |
40-| 📖 `read` | Read files (with line-range support) |
41-| 📝 `create` | Create a new file or fully overwrite an existing file |
42-| ✏️ `replace` | Replace or delete lines using hashline anchors |
43-| ➕ `insert` | Insert lines before/after an anchor without replacing |
44-| 🐚 `shell` | Run shell commands and see their output |
45-| 🤖 `subagent` | Spawn a focused mini-me for parallel subtasks |
36+| Tool | What it does |
37+| --------------- | ----------------------------------------------------------- |
38+| 🔍 `glob` | Find files by pattern across your project |
39+| 🧲 `grep` | Search file contents with regex |
40+| 📖 `read` | Read files (with line-range support) |
41+| 📝 `create` | Create a new file or fully overwrite an existing file |
42+| ✏️ `replace` | Replace or delete lines using hashline anchors |
43+| ➕ `insert` | Insert lines before/after an anchor without replacing |
44+| 🐚 `shell` | Run shell commands and see their output |
45+| 🤖 `subagent` | Spawn a focused mini-me for parallel subtasks |
46+| 🌐 `webSearch` | Search the web when `EXA_API_KEY` is set |
47+| 📄 `webContent` | Fetch full page content from URLs when `EXA_API_KEY` is set |
4648
47-I can also connect to **MCP servers** (like Exa for web search), giving you superpowers on demand.
49+Need more firepower? I connect to **MCP servers** over HTTP or stdio — bolt on external tools whenever the job calls for it.
4850
4951 ---
5052
5153 ## ⚡ Key Features
5254
53-- **Multi-provider** — set `OPENCODE_API_KEY` for Zen, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or just run Ollama locally. I auto-discover whatever's available.
55+- **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.
56+- **Built-in web search** — set `EXA_API_KEY` and I expose `webSearch` + `webContent` tools.
5457 - **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>`.
5558 - **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
56-- **Slash commands** — `/model` to switch models, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp` to manage MCP servers. See all with `/help`.
57-- **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
59+- **Slash commands** — `/model` or `/models` to list/switch models, `/model effort <low|medium|high|xhigh|off>` for reasoning effort, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp list|add|remove` to manage MCP servers, and `/exit` (`/quit`, `/q`) to leave. See all with `/help`.
60+- **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)
5861 - **Custom agents** — drop a `.md` file in `.agents/agents/` (or `~/.agents/agents/` globally) and reference it with `@agent-name` in your prompt. The agent runs in its own context window with a custom system prompt and optional model override. → [docs/custom-agents.md](docs/custom-agents.md)
59-- **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Skills are *never* auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
60-- **Post-tool hooks** — drop an executable at `.agents/hooks/post-<tool>` and I'll run it after every matching tool call.
62+- **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)
63+- **Post-tool hooks** — drop an executable at `.agents/hooks/post-<tool>` (or `~/.agents/hooks/post-<tool>` globally) and I'll run it after matching built-in tool calls. → [docs/tool-hooks.md](docs/tool-hooks.md)
6164 - **Beautiful, minimal output** — diffs for edits, formatted trees for file searches, a live status bar with model, git branch, and token counts.
62-- **16 ANSI colors only** — my output inherits *your* terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
65+- **16 ANSI colors only** — my output inherits _your_ terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
6366
6467 ---
6568
6669 ## 🧠 Interesting Things About Me
6770
68-- **I eat my own dog food.** I was built *by* a mini-coder agent. It's agents all the way down. 🐢
71+- **I eat my own dog food.** I was built _by_ a mini-coder agent. It's agents all the way down. 🐢
6972 - **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
7073 - **I respect existing conventions.** Hook scripts live in `.agents/hooks/`, context 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.
7174 - **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
@@ -73,40 +76,51 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
7376
7477 ---
7578
76-## 📁 The `.agents` folder
79+## 📁 Config folders
7780
78-mini-coder follows the [`.agents` convention](https://github.com/agentsmd/agents) used across the AI coding tool ecosystem. Drop files in `.agents/` to extend behaviour for the current repo, or `~/.agents/` to apply them globally.
81+I follow the [`.agents` convention](https://github.com/agentsmd/agents) — the shared standard across AI coding tools — and I also speak Claude Code's `.claude` format for **commands** and **skills**. Best of both worlds.
7982
80-| Path | What it does |
81-|---|---|
82-| `.agents/commands/*.md` | Custom slash commands (`/name`) |
83-| `.agents/agents/*.md` | Custom agents (`@name`) |
84-| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
85-| `.agents/hooks/post-<tool>` | Scripts run after a tool call |
86-| `AGENTS.md` | Project context injected into every system prompt |
83+| Path | What it does |
84+| -------------------------------- | ------------------------------------------------- |
85+| `.agents/commands/*.md` | Custom slash commands (`/name`) |
86+| `.claude/commands/*.md` | Claude-compatible custom commands |
87+| `.agents/agents/*.md` | Custom agents (`@name`) |
88+| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
89+| `.claude/skills/<name>/SKILL.md` | Claude-compatible skills |
90+| `.agents/hooks/post-<tool>` | Scripts run after supported built-in tool calls |
91+| `AGENTS.md` | Project context injected into every system prompt |
92+| `CLAUDE.md` | Fallback project context if `AGENTS.md` is absent |
93+| `~/.config/mini-coder/AGENTS.md` | Global fallback context |
8794
88-Local always overrides global. The same `~/.agents/` folder is shared with Claude Code, Opencode, and other compatible tools — skills and agents you write once work everywhere.
95+The pecking order is straightforward: local beats global, and `.agents` beats `.claude` at the same scope. Worth noting: custom agents are mini-coder-only — `.claude` compatibility is for commands and skills only. → [docs/configs.md](docs/configs.md)
8996
9097 ---
9198
92-
9399 ## 🚀 Getting Started
94100
101+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.
102+
95103 ```bash
96-# Install from npm
104+# Install globally
97105 bun add -g mini-coder
98106 # or: npm install -g mini-coder
99107
100-# Set your provider key (pick one — or run Ollama locally)
108+# Set a provider key (pick one — or run Ollama locally)
101109 export OPENCODE_API_KEY=your-zen-key # recommended
102-export ANTHROPIC_API_KEY=your-key # or direct Anthropic
103-export OPENAI_API_KEY=your-key # or direct OpenAI
110+export ANTHROPIC_API_KEY=your-key # direct Anthropic
111+export OPENAI_API_KEY=your-key # direct OpenAI
112+export GOOGLE_API_KEY=your-key # direct Gemini
113+# or: export GEMINI_API_KEY=your-key
114+
115+# Optional extras
116+export OLLAMA_BASE_URL=http://localhost:11434
117+export EXA_API_KEY=your-exa-key # enables webSearch/webContent
104118
105-# Launch!
119+# Launch
106120 mc
107121 ```
108122
109-Or run directly for a quick task:
123+Or drop me a prompt straight away and stay in the session:
110124
111125 ```bash
112126 mc "Refactor the auth module to use async/await"
@@ -115,14 +129,37 @@ mc "Refactor the auth module to use async/await"
115129 Useful flags:
116130
117131 ```bash
118-mc -c # continue last session
119-mc -r <id> # resume a specific session
120-mc -l # list recent sessions
121-mc -m zen/claude-sonnet-4-6 # pick a model
132+mc -c # continue last session
133+mc -r <id> # resume a specific session
134+mc -l # list recent sessions
135+mc -m zen/claude-sonnet-4-6 # pick a model
136+mc --cwd ~/src/other-project # set working directory
137+mc -h # show help
122138 ```
123139
124140 ---
125141
142+## 🗃️ App data
143+
144+Everything I remember lives in `~/.config/mini-coder/` — here's what I'm holding onto:
145+
146+- `sessions.db` — your full session history, `/undo` snapshots, MCP server config, and model metadata, all in one tidy SQLite file
147+- `api.log` — a request/response log for every provider call this run, if you want to peek under the hood
148+- `errors.log` — anything that went sideways, caught and written down so you can actually debug it
149+- `AGENTS.md` — your global context fallback, quietly injected whenever a repo doesn't bring its own `AGENTS.md` or `CLAUDE.md`
150+
151+---
152+
153+## 📚 Go Deeper
154+
155+The README hits the highlights — the docs have the full story:
156+
157+- [docs/custom-commands.md](docs/custom-commands.md)
158+- [docs/custom-agents.md](docs/custom-agents.md)
159+- [docs/skills.md](docs/skills.md)
160+- [docs/configs.md](docs/configs.md)
161+- [docs/tool-hooks.md](docs/tool-hooks.md)
162+
126163 ## 🗂️ Project Structure
127164
128165 ```
@@ -132,7 +169,7 @@ src/
132169 cli/ # Input, output, slash commands, markdown rendering
133170 llm-api/ # Provider factory + streaming turn logic
134171 tools/ # glob, grep, read, create, replace, insert, shell, subagent
135- # + hashline anchors, diffs, hooks, snapshots
172+ # + webSearch, webContent, hashline anchors, diffs, hooks, snapshots
136173 mcp/ # MCP server connections
137174 session/ # SQLite-backed session & history management
138175 ```
@@ -154,16 +191,15 @@ src/
154191
155192 > Accurate. Fast. Focused on the conversation.
156193
157-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.
194+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.
158195
159196 ---
160197
161198 ## 💬 What People Are Saying
162199
163200 > "sean this is fucking sick"
164-> — [vpr99](https://github.com/vpr99) (eric)
201+> — [vpr99](https://github.com/vpr99)
165202
166203 ---
167204
168-
169-*Built with ❤️ and a healthy obsession with terminal aesthetics.*
205+_Built with ❤️ and a healthy obsession with terminal aesthetics._