xonecas.io
64875
Mc

mini-coder / commit 4b029dc

docs: align docs with current behavior

xonecas2026-03-11 4b029dc64103f39c0b0f722c8edc0f49bb8bcf5e parent fcd6929

8 files changed

README.md+20−17
@@ -56,10 +56,10 @@ Need more firepower? I connect to **MCP servers** over HTTP or stdio — bolt on
5656 - **Built-in web search** — set `EXA_API_KEY` and I expose `webSearch` + `webContent` tools.
5757 - **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>`.
5858 - **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
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 le …
59+- **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, `/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, …
6060
6161 - **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)
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)
62+- **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`. `@agent-name` is supported for completion and is a useful prompt convention. → [docs/custom-agents.md](docs/custom-agents.md)
6363 - **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)
6464 - **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)
6565 - **Beautiful, minimal output** — diffs for edits, formatted trees for file searches, a live status bar with model, git branch, and token counts.
@@ -73,28 +73,32 @@ Need more firepower? I connect to **MCP servers** over HTTP or stdio — bolt on
7373 - **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
7474 - **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.
7575 - **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
76-- **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 3 levels deep.)
76+- **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.)
7777
7878 ---
7979
8080 ## 📁 Config folders
8181
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.
82+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**.
8383
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 |
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 |
89+| `.claude/agents/*.md` | Alternate `.claude` path for custom agents |
90+| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
91+| `.claude/skills/<name>/SKILL.md` | Claude-compatible skills |
92+| `.agents/hooks/post-<tool>` | Scripts run after supported built-in tool calls |
93+| `.agents/AGENTS.md` | Preferred local project context |
94+| `CLAUDE.md` | Local fallback context if `.agents/AGENTS.md` is absent |
95+| `AGENTS.md` | Local fallback context if `.agents/AGENTS.md` and `CLAUDE.md` are absent |
96+| `~/.agents/AGENTS.md` | Preferred global context, prepended before local context |
97+| `~/.agents/CLAUDE.md` | Global fallback context if `~/.agents/AGENTS.md` is absent |
9598
99+Global commands, agents, and skills also work from `~/.agents/...` and `~/.claude/...`.
96100
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)
101+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)
98102
99103 ---
100104
@@ -148,7 +152,6 @@ Everything I remember lives in `~/.config/mini-coder/` — here's what I'm holdi
148152 - `sessions.db` — your full session history, `/undo` snapshots, MCP server config, and model metadata, all in one tidy SQLite file
149153 - `api.log` — a request/response log for every provider call this run, if you want to peek under the hood
150154 - `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`
152155
153156 ---
154157
SHARE.md+4−3
@@ -12,10 +12,11 @@ mc
1212 - **Session memory** — local SQLite, resume with `mc -c`
1313 - **Shell integration** — `!command` inline, `@file` references with tab completion
1414 - **Subagents** — spawns parallel agents for independent subtasks
15-- **MCP support** — connect tools like Exa web search
16-- **Hooks** — auto-run scripts after any tool call via `.agents/hooks/`
15+- **Built-in web search** — enable Exa-backed `webSearch`/`webContent` with `EXA_API_KEY`
16+- **MCP support** — connect external tools and servers
17+- **Hooks** — auto-run scripts after supported built-in tool calls via `.agents/hooks/`
1718 - **16 ANSI colors** — inherits your terminal theme, always
1819
1920 No telemetry. No cloud accounts. No bloat.
2021
21-🔗 https://github.com/sacenox/mini-coder
22+🔗 https://github.com/sacenox/mini-coder
docs/configs.md+40−8
@@ -1,13 +1,13 @@
11 # Config conventions
22
3-mini-coder supports both its native `.agents` convention and Claude Code's `.claude` convention for commands and skills.
3+mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
44
55 ## Supported config roots
66
77 | Root | Purpose |
88 |---|---|
99 | `.agents/` | mini-coder native config |
10-| `.claude/` | Claude Code-compatible commands/skills |
10+| `.claude/` | Alternate config layout supported by mini-coder |
1111
1212 Each root can exist in:
1313
@@ -58,20 +58,52 @@ Skill instructions/content.
5858
5959 If `name` is omitted, folder name is used.
6060
61-## Agents (mini-coder specific)
61+## Agents
6262
63-Custom subagents are configured in `.agents`:
63+Supported locations:
6464
6565 - `./.agents/agents/*.md`
6666 - `~/.agents/agents/*.md`
67+- `./.claude/agents/*.md`
68+- `~/.claude/agents/*.md`
69+
70+Format:
71+
72+```md
73+---
74+description: Optional help text
75+model: optional/model-override
76+mode: optional agent mode
77+---
78+
79+Agent system prompt.
80+```
81+
82+## Context files
83+
84+mini-coder loads at most one global context file and at most one local context file, then includes both when present.
85+
86+Global lookup order:
87+
88+1. `~/.agents/AGENTS.md`
89+2. `~/.agents/CLAUDE.md`
90+
91+Local lookup order:
92+
93+1. `./.agents/AGENTS.md`
94+2. `./CLAUDE.md`
95+3. `./AGENTS.md`
96+
97+Injection order:
6798
68-(There is no `.claude` compatibility path for agents. Claude doesn't have custom subagents)
99+1. Global context (if found)
100+2. Local context (if found)
69101
70102 ## Precedence and conflicts
71103
72-Precedence rules:
104+Precedence rules for commands, skills, and agents:
73105
74106 1. **Local overrides global**
75-2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same command/skill name, **`.agents` wins**
107+2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
76108
77-When same-scope conflicts are detected for commands/skills, mini-coder prints a warning and uses the `.agents` version.
109+When same-scope conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.
docs/custom-agents.md+14−13
@@ -1,7 +1,7 @@
11 # Custom Agents
22
3-An agent is a subagent with a custom system prompt and optional model override.
4-Use `@agent-name` anywhere in your prompt to route the message through it.
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.
55
66 ## Where to put them
77
@@ -9,8 +9,10 @@ Use `@agent-name` anywhere in your prompt to route the message through it.
99 |---|---|
1010 | `.agents/agents/*.md` | Current repo only |
1111 | `~/.agents/agents/*.md` | All projects (global) |
12+| `.claude/agents/*.md` | Current repo only (`.claude` layout) |
13+| `~/.claude/agents/*.md` | All projects (global, `.claude` layout) |
1214
13-Local agents override global ones with the same name.
15+Local agents override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
1416
1517 ## Create an agent
1618
@@ -33,12 +35,11 @@ No flattery. End with a one-line verdict.
3335 Then in the REPL:
3436
3537 ```
36-@reviewer review the auth module for race conditions
38+/agent reviewer
39+review the auth module for race conditions
3740 ```
3841
39-The rest of the message (everything except the `@reviewer` token) becomes
40-the prompt. The agent runs in its own context window and returns its output
41-into the conversation.
42+You can also mention `@reviewer` in a prompt as a naming convention, and agent names participate in `@` tab completion alongside skills and files.
4243
4344 ## Frontmatter fields
4445
@@ -46,22 +47,22 @@ into the conversation.
4647 |---|---|---|
4748 | `description` | No | Shown in `/help`. Defaults to filename. |
4849 | `model` | No | Override the active model for this agent. |
49-| `mode` | No | `primary` — interactive only (via `/agent <name>`); `subagent` — callable via the `subagent` tool only (default); `all` — both. |
50-
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>`. |
5151
5252 The markdown body (after frontmatter) is the agent's system prompt.
5353
5454 ## Combining with files
5555
56-`@file` references are resolved before the agent fires:
56+File references are resolved before the prompt is sent:
5757
5858 ```
59-@reviewer @src/auth/session.ts check this file for issues
59+/agent reviewer
60+@src/auth/session.ts check this file for issues
6061 ```
6162
6263 ## Tab completion
6364
64-Type `@` and press `Tab` to autocomplete agent names alongside files.
65+Type `@` and press `Tab` to autocomplete agent names alongside skills and files.
6566
6667 ## Listing agents
6768
@@ -69,4 +70,4 @@ Type `@` and press `Tab` to autocomplete agent names alongside files.
6970 /help
7071 ```
7172
72-Agents are listed in magenta, tagged `(local)` or `(global)`.
73+Agents are listed in magenta, tagged `(local)` or `(global)`.
docs/custom-commands.md+4−9
@@ -8,8 +8,10 @@ Custom commands let you define reusable prompts that run as `/command` in the mi
88 |---|---|
99 | `.agents/commands/*.md` | Current repo only |
1010 | `~/.agents/commands/*.md` | All projects (global) |
11+| `.claude/commands/*.md` | Current repo only (Claude-compatible) |
12+| `~/.claude/commands/*.md` | All projects (global, Claude-compatible) |
1113
12-Local commands override global ones with the same name.
14+Local commands override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
1315
1416 ## Create a command
1517
@@ -21,7 +23,6 @@ Create a markdown file. The filename becomes the command name.
2123 ---
2224 description: Summarise what changed since yesterday
2325 model: zen/claude-haiku-4-5
24-
2526 ---
2627
2728 Run `!`git log --oneline --since=yesterday`` and summarise the changes
@@ -44,8 +45,6 @@ Then in the REPL:
4445 | `subtask` | No | Set to `true` to force subagent execution (OpenCode-compatible alias for `context: fork`). |
4546 | `agent` | No | Run the command under a named agent's system prompt (only applies when `context: fork`). |
4647
47-
48-
4948 ## Arguments
5049
5150 Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
@@ -56,7 +55,6 @@ Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for indiv
5655 ---
5756 description: Search the codebase for a topic
5857 model: zen/claude-haiku-4-5
59-
6058 ---
6159
6260 Search the codebase for: $ARGUMENTS
@@ -117,7 +115,6 @@ lightweight tasks regardless of what the session is currently set to.
117115 ---
118116 description: Quick grep for a symbol
119117 model: zen/claude-haiku-4-5
120-
121118 ---
122119
123120 Find all usages of $ARGUMENTS across the codebase using grep and glob.
@@ -126,7 +123,6 @@ List each occurrence with file path and line number. No explanations needed.
126123
127124 Large models for deep analysis, small models for search and lookup.
128125
129-
130126 ## Precedence
131127
132128 Custom commands shadow built-ins. If you create `.agents/commands/plan.md`
@@ -134,7 +130,6 @@ it will replace the built-in `/plan` for that project. The global `/review`
134130 command (auto-created at `~/.agents/commands/review.md` on first run) works
135131 the same way — a local `.agents/commands/review.md` will override it.
136132
137-
138133 ## Listing commands
139134
140135 ```
@@ -142,4 +137,4 @@ the same way — a local `.agents/commands/review.md` will override it.
142137 ```
143138
144139 Custom commands are listed at the bottom under **custom commands**, tagged
145-with `(local)` or `(global)`.
140+with `(local)` or `(global)`.
docs/skills.md+5−3
@@ -15,8 +15,10 @@ Each skill is a folder containing a `SKILL.md`:
1515 |---|---|
1616 | `.agents/skills/<name>/SKILL.md` | Current repo only |
1717 | `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
18+| `.claude/skills/<name>/SKILL.md` | Current repo only (Claude-compatible) |
19+| `~/.claude/skills/<name>/SKILL.md` | All projects (global, Claude-compatible) |
1820
19-Local skills override global ones with the same name.
21+Local skills override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
2022
2123 ## Create a skill
2224
@@ -60,7 +62,7 @@ included in the message sent to the LLM.
6062
6163 ## Tab completion
6264
63-Type `@` and press `Tab` to autocomplete skill names alongside files.
65+Type `@` and press `Tab` to autocomplete skill names alongside agents and files.
6466
6567 ## Listing skills
6668
@@ -68,4 +70,4 @@ Type `@` and press `Tab` to autocomplete skill names alongside files.
6870 /help
6971 ```
7072
71-Skills are listed in yellow, tagged `(local)` or `(global)`.
73+Skills are listed in yellow, tagged `(local)` or `(global)`.
mini-coder-idea.md+20−13
@@ -16,27 +16,34 @@ Elegant output that focus on the conversation with the agent and their actions.
1616 Accurate and reliable core set of features.
1717 Fast and performant
1818 Community oriented, all of the inspirations have their own dotfile format, try to follow the existing
19-conventions and not introduce more specs. (skills.sh installs to `.agents,AGENTS.md` which could be a good one for us)
19+conventions and not introduce more specs. (`.agents` / `AGENTS.md`, while also supporting adjacent conventions like `.claude`)
2020
2121 ## Features:
2222
2323 - Auto discovery of providers via ENV (Example: OPENCODE_API_KEY), or local servers (Example: ollama)
2424 - Session management and command to create new/resume/list with local sqlite file.
25-- Seamless shell integration with aliases and completions with `!` in prompt input.
26-- Reference files, skills, agents from the working directory and global community configs with `@` in prompt input
25+- Seamless shell integration with `!` in prompt input.
26+- Reference files and skills from the working directory and global configs with `@` in prompt input, plus autocomplete for files, skills, and agents.
2727 - Press `ESC` at any point during an assistant response to interrupt it: the partial response is preserved in history with an interrupt stub appended (so the LLM retains context), and the user is returned to the prompt silently. `ctrl+c` exits the app. `ctrl+d` (EOF) also exits.
2828
2929 - `glob`, `grep`, `read`, `replace`,`insert`, `create`, `shell`, and `subagent` tools for LLMs
30-- `subagent` tool spawns a fresh `mc` subprocess — full capability parity with the main agent, correct working directory, and support for recursive subagents. Custom agents (from `.agents/agents/`) and custom commands (from `.agents/commands/`) are fully supported in subagents.
31-- tool hooks support (do command automatically after certain tools)
30+- Optional `webSearch` and `webContent` tools when `EXA_API_KEY` is set.
31+- `subagent` tool spawns a fresh `mc` subprocess — full capability parity with the main agent, support for recursive subagents (up to 10 levels), and git worktree isolation/merge-back when available. Custom agents and custom commands from `.agents` and `.claude` are supported in subagents.
32+- tool hooks support for supported built-in tools
3233 - Commands in CLI prompt:
3334 - `/model` command allows the user to pick a model from connected providers. As well as thinking effort for the model if supported. Selection persists accross sessions.
34- - `/review` command sends a subagent with a specific prompt to review code well
35- - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
35+ - `/undo` removes the last turn from conversation history.
36+ - `/reasoning` toggles display of model reasoning output.
37+ - `/context` configures context pruning and tool-result caps.
38+ - `/review` reviews recent changes via a global command installed at app start (`~/.agents/commands/review.md`), and can be customized or shadowed locally.
39+
3640 - `/plan` for a read-only mode (`/plan` again to turn off)
3741 - `/ralph` for a ralph loop mode (by Geoffrey Huntley, who described it simply: “Ralph is a Bash loop.”)
38-- Connect to streaming MCPs (Example: https://exa.ai/docs/reference/exa-mcp)
39-- Image and clipboard support, pasting images and text
42+ - `/agent` sets or clears the active primary agent.
43+ - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
44+ - `/new` starts a new session with clean context.
45+- Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
46+- Image support in prompt input, including pasted image data URLs and pasted image file paths.
4047
4148 ## UI/Output
4249
@@ -46,7 +53,7 @@ conventions and not introduce more specs. (skills.sh installs to `.agents,AGENTS
4653 - Read tools (glob, grep, read) show the tool call with args fomatted for output
4754 - Edit tools show the diff applied
4855 - Shell tools show the command called and their output
49-- status bar under prompt, with current model/provider/cwd/git branch/unique context size/token ouput/token input
56+- status bar under prompt, with current model/provider/session/git branch/active agent/thinking effort/context usage/token input/token output
5057 - some prompt animation when a turn is processing.
5158
5259 ## Tech stack
@@ -65,6 +72,6 @@ Core modules:
6572 - `llm-api`: Provides the api to intereact with the provider and process the full conversation turn + tool calling.
6673 - `cli`: Output/UI
6774 - `agent`: Main agent implementation
68-- `tools/subagent`: subagent tool — spawns a fresh `mc` subprocess, handles worktree lifecycle and structured result handback
69-- `tools/read-write-shell`: all of the tools that use the local filesystem/shell
70-- `mcp`: handles connecting to mcp servers
75+- `tools`: local filesystem, shell, subagent, and web/search helpers
76+- `session`: sqlite-backed sessions, settings, model info, and MCP server storage
77+- `mcp`: handles connecting to mcp servers
src/index.ts+2−0
@@ -152,6 +152,8 @@ function printHelp(): void {
152152 ["ANTHROPIC_API_KEY", "Anthropic direct"],
153153 ["OPENAI_API_KEY", "OpenAI direct"],
154154 ["GOOGLE_API_KEY", "Google Gemini direct"],
155+ ["GEMINI_API_KEY", "Gemini direct (alias for GOOGLE_API_KEY)"],
156+ ["EXA_API_KEY", "Enables webSearch and webContent tools"],
155157 ["OLLAMA_BASE_URL", "Ollama base URL (default: http://localhost:11434)"],
156158 ];
157159 for (const [env, desc] of envs) {