@@ -1,65 +1,170 @@
11 ---
22 name: mini-coder
3-description: Architecture and conventions for the mini-coder codebase
3+description: How to use the `mc` CLI coding agent
44 ---
55
66 # mini-coder
77
8-mini-coder is a small, fast CLI coding agent built with Bun and TypeScript.
8+Use this skill when you need to help a user operate the `mc` command-line tool.
99
10-## Key source paths
10+`mc` is the executable for **mini-coder**, a small CLI coding agent. This skill is about **how to use the tool**, not how the mini-coder repo is implemented.
1111
12-| Path | Purpose |
13-|------|---------|
14-| `src/agent/` | Core agent loop, session runner, subagent runner, system prompt builder |
15-| `src/cli/` | CLI commands, custom commands, agents/skills loaders, input/output rendering |
16-| `src/llm-api/` | Provider abstraction, turn streaming, model metadata |
17-| `src/tools/` | All tools (read, replace, insert, create, shell, subagent, exa, …) |
18-| `src/session/` | Session manager and SQLite DB repositories |
19-| `src/mcp/` | MCP client integration |
20-| `.agents/` | Local config: agents, commands, skills, hooks |
12+## What `mc` does
2113
22-## Config system
14+- Starts an interactive coding session in the terminal
15+- Accepts a one-shot prompt from the command line
16+- Persists sessions locally so they can be resumed
17+- Lets users switch models, manage MCP servers, and load custom agents/skills/commands
2318
24-All config lives under `.agents/` (or `~/.agents/` globally). Local wins over global; within the same scope, `.agents/` wins over `.claude/`.
19+## Core command-line usage
2520
26-| Type | Path | Strategy |
27-|------|------|----------|
28-| Agents | `.agents/agents/<name>.md` | flat — one `.md` per agent |
29-| Commands | `.agents/commands/<name>.md` | flat — one `.md` per command |
30-| Skills | `.agents/skills/<name>/SKILL.md` | nested — one directory per skill |
21+```sh
22+mc
23+mc "explain this codebase"
24+mc -c
25+mc -r <session-id>
26+mc -l
27+mc -m <model-id>
28+mc --cwd <path>
29+mc -h
30+```
31+
32+## Most common flows
3133
32-### Frontmatter fields
34+### Start an interactive session
3335
34-- `description` — shown in `/help` and agent/skill listings
35-- `model` — override the LLM model for this config (commands: only used when `context: fork`)
36-- `mode` — `primary` / `subagent` / `all` (agents only; default: `subagent`)
37-- `agent` — run command under a named agent's system prompt (commands: only used when `context: fork`)
38-- `name` — override the key name (nested skills only; defaults to folder name)
39-- `context` — `fork` to run command as isolated subagent; default is inline in current conversation (commands only; Claude Code standard)
40-- `subtask` — `true` to force subagent invocation (commands only; OpenCode compat, equivalent to `context: fork`)
36+```sh
37+mc
38+```
4139
42-### Agent modes
40+Use this when the user wants a normal back-and-forth coding session.
4341
44-- `primary` — activated interactively via `/agent <name>` in the CLI
45-- `subagent` — callable via the `subagent` tool (the default when `mode` is omitted)
46-- `all` — available in both contexts
42+### Run a prompt immediately
43+
44+```sh
45+mc "refactor the auth module to use async/await"
46+```
47+
48+Use this when the user already knows the task they want to give `mc`.
49+
50+### Continue a previous session
51+
52+```sh
53+mc -c
54+mc -r <session-id>
55+mc -l
56+```
4757
48-## Tools
58+- `mc -c` continues the most recent session
59+- `mc -r <session-id>` resumes a specific session
60+- `mc -l` lists recent sessions so the user can find an ID
4961
50-Every tool is declared in `src/agent/tools.ts`. Core tools: `read`, `replace`, `insert`, `create`, `shell`, `subagent`, `webSearch`, `webContent`.
62+### Pick a model
5163
52-Hooks in `.agents/hooks/` fire after any of the 5 hookable tools: `read`, `create`, `replace`, `insert`, `shell`. The repo currently uses `post-create`, `post-insert`, and `post-replace` to auto-format changed files.
64+```sh
65+mc -m zen/claude-sonnet-4-6
66+mc -m ollama/llama3.2
67+```
5368
69+Use `-m` when the user wants a specific provider or local model.
5470
55-## Testing
71+### Run in another directory
5672
73+```sh
74+mc --cwd ~/src/other-project
5775 ```
58-bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun test
76+
77+Useful when the user is not already inside the target repo.
78+
79+## Interactive slash commands
80+
81+Inside `mc`, the user can run slash commands such as:
82+
83+- `/help` — show help
84+- `/model` — list models
85+- `/model <id>` — switch models
86+- `/model effort <low|medium|high|xhigh|off>` — set reasoning effort when supported
87+- `/reasoning [on|off]` — toggle reasoning display
88+- `/context prune <off|balanced|aggressive>` — set pruning strategy
89+- `/context cap <off|bytes|kb>` — cap tool payload size
90+- `/cache <on|off>` — toggle prompt caching
91+- `/plan` — toggle read-only planning mode
92+- `/ralph` — toggle autonomous execution looping
93+- `/undo` — revert the last turn
94+- `/new` — start a fresh session
95+- `/mcp list` — list configured MCP servers
96+- `/mcp add <name> http <url>` — add an HTTP MCP server
97+- `/mcp add <name> stdio <cmd> [args...]` — add a stdio MCP server
98+- `/mcp remove <name>` — remove an MCP server
99+- `/agent [name]` — set or clear an active primary custom agent
100+- `/exit`, `/quit`, `/q` — leave the session
101+
102+## Prompt input features
103+
104+### Shell input
105+
106+If the user starts a prompt with `!`, `mc` runs that shell command inline and can use the result in context.
107+
108+### References with `@`
109+
110+`mc` supports `@` references in prompts for:
111+
112+- files
113+- custom agents
114+- skills
115+
116+This helps users quickly pull relevant context into a prompt.
117+
118+## Config locations
119+
120+mini-coder supports both `.agents` and `.claude` config layouts.
121+
122+### Local config in a repo
123+
124+- `.agents/commands/*.md`
125+- `.agents/agents/*.md`
126+- `.agents/skills/<name>/SKILL.md`
127+- `.agents/hooks/post-<tool>`
128+
129+### Global config in the home directory
130+
131+- `~/.agents/commands/*.md`
132+- `~/.agents/agents/*.md`
133+- `~/.agents/skills/<name>/SKILL.md`
134+
135+Same ideas also work under `.claude/` and `~/.claude/`.
136+
137+## Data and state
138+
139+mini-coder stores app data in:
140+
141+```text
142+~/.config/mini-coder/
59143 ```
60144
61-Tests are `*.test.ts` files co-located with source. Write minimal tests focused on our own logic — no mocks, no stubs, no mock servers.
145+This includes session history and related local state.
146+
147+## How to help users effectively
62148
63-## Data
149+When answering questions about `mc`:
150+
151+- Prefer giving exact commands the user can paste
152+- Distinguish clearly between **shell commands** (run before or around `mc`) and **slash commands** (run inside `mc`)
153+- Suggest `mc -h` or `/help` when the user needs command discovery
154+- Suggest `mc -l`, `mc -c`, or `mc -r <id>` for session recovery
155+- Mention `--cwd` when the problem is about the wrong working directory
156+- Mention `-m <model-id>` when the problem is model selection
157+- Mention MCP commands only when the user is integrating external tools
158+
159+## Examples to suggest
160+
161+```sh
162+mc
163+mc "add tests for src/tools/replace.ts"
164+mc -c
165+mc -l
166+mc -m zen/claude-sonnet-4-6
167+mc --cwd ~/src/my-project
168+```
64169
65-App data: `~/.config/mini-coder/` — SQLite DB for sessions, model info, MCP servers, and settings.
170+If a user asks how to do something in mini-coder, answer in terms of the `mc` CLI and its interactive commands.