mini-coder 0.0.15 β†’ 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +84 -46
  2. package/dist/mc.js +3866 -3488
  3. package/docs/custom-agents.md +2 -0
  4. package/docs/custom-commands.md +16 -27
  5. package/package.json +12 -12
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # πŸ‘Ύ mini-coder
6
6
 
7
- > *Small. Fast. Gets out of your way.*
7
+ > _Small. Fast. Gets out of your way._
8
8
 
9
9
  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.
10
10
 
@@ -31,41 +31,45 @@ $ mc
31
31
 
32
32
  ## πŸ› οΈ What Can I Do?
33
33
 
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:
35
35
 
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 |
46
48
 
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.
48
50
 
49
51
  ---
50
52
 
51
53
  ## ⚑ Key Features
52
54
 
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.
54
57
  - **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>`.
55
58
  - **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 (global custom command, auto-created at `~/.agents/commands/review.md`), `/agent [name]` to set or clear an active primary agent, `/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
+
61
+ - **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)
58
62
  - **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.
63
+ - **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)
64
+ - **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)
61
65
  - **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.
66
+ - **16 ANSI colors only** β€” my output inherits _your_ terminal theme. Dark mode, light mode, Solarized, Gruvbox β€” I fit right in.
63
67
 
64
68
  ---
65
69
 
66
70
  ## 🧠 Interesting Things About Me
67
71
 
68
- - **I eat my own dog food.** I was built *by* a mini-coder agent. It's agents all the way down. 🐒
72
+ - **I eat my own dog food.** I was built _by_ a mini-coder agent. It's agents all the way down. 🐒
69
73
  - **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) β€” fast startup, native TypeScript, and a built-in SQLite driver.
70
74
  - **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.
71
75
  - **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
@@ -73,40 +77,52 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
73
77
 
74
78
  ---
75
79
 
76
- ## πŸ“ The `.agents` folder
80
+ ## πŸ“ Config folders
77
81
 
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.
82
+ 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.
79
83
 
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 |
84
+ | Path | What it does |
85
+ | -------------------------------- | ------------------------------------------------- |
86
+ | `.agents/commands/*.md` | Custom slash commands (`/name`) |
87
+ | `.claude/commands/*.md` | Claude-compatible custom commands |
88
+ | `.agents/agents/*.md` | Custom agents (`@name`) |
89
+ | `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
90
+ | `.claude/skills/<name>/SKILL.md` | Claude-compatible skills |
91
+ | `.agents/hooks/post-<tool>` | Scripts run after supported built-in tool calls |
92
+ | `AGENTS.md` | Project context injected into every system prompt |
93
+ | `CLAUDE.md` | Fallback project context if `AGENTS.md` is absent |
94
+ | `~/.agents/AGENTS.md` | Global fallback context |
87
95
 
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.
89
96
 
90
- ---
97
+ 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)
91
98
 
99
+ ---
92
100
 
93
101
  ## πŸš€ Getting Started
94
102
 
103
+ 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.
104
+
95
105
  ```bash
96
- # Install from npm
106
+ # Install globally
97
107
  bun add -g mini-coder
98
108
  # or: npm install -g mini-coder
99
109
 
100
- # Set your provider key (pick one β€” or run Ollama locally)
110
+ # Set a provider key (pick one β€” or run Ollama locally)
101
111
  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
112
+ export ANTHROPIC_API_KEY=your-key # direct Anthropic
113
+ export OPENAI_API_KEY=your-key # direct OpenAI
114
+ export GOOGLE_API_KEY=your-key # direct Gemini
115
+ # or: export GEMINI_API_KEY=your-key
104
116
 
105
- # Launch!
117
+ # Optional extras
118
+ export OLLAMA_BASE_URL=http://localhost:11434
119
+ export EXA_API_KEY=your-exa-key # enables webSearch/webContent
120
+
121
+ # Launch
106
122
  mc
107
123
  ```
108
124
 
109
- Or run directly for a quick task:
125
+ Or drop me a prompt straight away and stay in the session:
110
126
 
111
127
  ```bash
112
128
  mc "Refactor the auth module to use async/await"
@@ -115,14 +131,37 @@ mc "Refactor the auth module to use async/await"
115
131
  Useful flags:
116
132
 
117
133
  ```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
134
+ mc -c # continue last session
135
+ mc -r <id> # resume a specific session
136
+ mc -l # list recent sessions
137
+ mc -m zen/claude-sonnet-4-6 # pick a model
138
+ mc --cwd ~/src/other-project # set working directory
139
+ mc -h # show help
122
140
  ```
123
141
 
124
142
  ---
125
143
 
144
+ ## πŸ—ƒοΈ App data
145
+
146
+ Everything I remember lives in `~/.config/mini-coder/` β€” here's what I'm holding onto:
147
+
148
+ - `sessions.db` β€” your full session history, `/undo` snapshots, MCP server config, and model metadata, all in one tidy SQLite file
149
+ - `api.log` β€” a request/response log for every provider call this run, if you want to peek under the hood
150
+ - `errors.log` β€” anything that went sideways, caught and written down so you can actually debug it
151
+ - `AGENTS.md` β€” your global context fallback, quietly injected whenever a repo doesn't bring its own `AGENTS.md` or `CLAUDE.md`
152
+
153
+ ---
154
+
155
+ ## πŸ“š Go Deeper
156
+
157
+ The README hits the highlights β€” the docs have the full story:
158
+
159
+ - [docs/custom-commands.md](docs/custom-commands.md)
160
+ - [docs/custom-agents.md](docs/custom-agents.md)
161
+ - [docs/skills.md](docs/skills.md)
162
+ - [docs/configs.md](docs/configs.md)
163
+ - [docs/tool-hooks.md](docs/tool-hooks.md)
164
+
126
165
  ## πŸ—‚οΈ Project Structure
127
166
 
128
167
  ```
@@ -132,7 +171,7 @@ src/
132
171
  cli/ # Input, output, slash commands, markdown rendering
133
172
  llm-api/ # Provider factory + streaming turn logic
134
173
  tools/ # glob, grep, read, create, replace, insert, shell, subagent
135
- # + hashline anchors, diffs, hooks, snapshots
174
+ # + webSearch, webContent, hashline anchors, diffs, hooks, snapshots
136
175
  mcp/ # MCP server connections
137
176
  session/ # SQLite-backed session & history management
138
177
  ```
@@ -154,16 +193,15 @@ src/
154
193
 
155
194
  > Accurate. Fast. Focused on the conversation.
156
195
 
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.
196
+ 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.
158
197
 
159
198
  ---
160
199
 
161
200
  ## πŸ’¬ What People Are Saying
162
201
 
163
202
  > "sean this is fucking sick"
164
- > β€” [vpr99](https://github.com/vpr99) (eric)
203
+ > β€” [vpr99](https://github.com/vpr99)
165
204
 
166
205
  ---
167
206
 
168
-
169
- *Built with ❀️ and a healthy obsession with terminal aesthetics.*
207
+ _Built with ❀️ and a healthy obsession with terminal aesthetics._