xonecas.io
64875
Mc

mini-coder / commit 7ffaa7d

refactor: complete shell-first file helper cleanup

xonecas2026-03-15 7ffaa7d9c33bda99e5787b850b3796775cbc408a parent 3964cc6

19 files changed

.agents/hooks/post-create+0−2
@@ -1,2 +0,0 @@
1-#!/bin/bash
2-bun run lint --write "$FILEPATH" 2>/dev/null || true
.agents/hooks/post-insert+0−2
@@ -1,2 +0,0 @@
1-#!/bin/bash
2-bun run lint --write "$FILEPATH" 2>/dev/null || true
.agents/hooks/post-replace+0−2
@@ -1,2 +0,0 @@
1-#!/bin/bash
2-bun run lint --write "$FILEPATH" 2>/dev/null || true
AGENTS.md+1−1
@@ -7,7 +7,7 @@
77 - Keep the repo pristine: no failing tests, no lint, no build issues, no `nolint:` comments.
88 - Use `bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test` to check your changes.
99 - We care about performance.
10-- Don't worry about formatting issues, formatting happens automatically on mutations. (see .agents/hooks)
10+- Don't worry about formatting issues, formatting happens automatically on mutations.
1111 - Do not inline `import` calls. Don't duplicate code. Don't leave dead code behind.
1212 - Don't make random test files, if you need to test something, write a propper unit test.
1313 - If you make temp files, clean them up when you are done.
README.md+2−0
@@ -35,6 +35,8 @@ My toolkit is lean on purpose — every tool earns its spot, no passengers:
3535 | 🌐 `webSearch` | Search the web when `EXA_API_KEY` is set |
3636 | 📄 `webContent` | Fetch full page content from URLs when `EXA_API_KEY` is set |
3737
38+mini-coder is intentionally **shell-first**: inspect with shell, edit with `mc-edit`, verify with shell.
39+
3840 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.
3941
4042 ---
SHARE.md+1−1
@@ -14,7 +14,7 @@ mc
1414 - **Subagents** — spawns parallel agents for independent subtasks
1515 - **Built-in web search** — enable Exa-backed `webSearch`/`webContent` with `EXA_API_KEY`
1616 - **MCP support** — connect external tools and servers
17-- **Hooks** — auto-run scripts after supported built-in tool calls via `.agents/hooks/`
17+- **Shell-first editing** — inspect with shell, make targeted edits with `mc-edit`, verify with shell
1818 - **16 ANSI colors** — inherits your terminal theme, always
1919
2020 No telemetry. No cloud accounts. No bloat.
TODO.md+2−2
@@ -14,13 +14,13 @@
1414
1515 ---
1616
17-## LSP Diagnostics (not very important, with tool-hooks and strong linting, this is not as necessary, but we should implement asap)
17+## LSP Diagnostics (not very important, with strong linting this is not as necessary, but we should implement asap)
1818
1919 We should have a closed loop feedback for LSP diagnostics on edits/reads.
2020
2121 This could potentially be a very big slowdown, waiting for updated diagnostics every edit. This also has bias downsides, stale diagnostics confuse the LLM, and can cause negative distractions.
2222
23-We need to do research first, but maybe we can leverage the hooks feature to achieve a similar result without the performance penalties? Needs brainstorming
23+We need to do research first and find an approach that fits the current shell-first architecture without the performance penalties. Needs brainstorming
2424
2525 ---
2626
docs/configs.md+2−0
@@ -2,6 +2,8 @@
22
33 mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
44
5+Only commands, skills, agents, and context files are loaded from these roots. Hook directories are ignored.
6+
57 ## Supported config roots
68
79 | Root | Purpose |
docs/custom-agents.md+2−0
@@ -3,6 +3,8 @@
33 A custom agent is a reusable system prompt with an optional model override.
44 You can activate one with `/agent <name>`, and non-`primary` agents are also exposed to the `subagent` tool.
55
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+
68 ## Where to put them
79
810 | Location | Scope |
docs/custom-commands.md+2−0
@@ -2,6 +2,8 @@
22
33 Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
44
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+
57 ## Where to put them
68
79 | Location | Scope |
docs/file-helper-plan.md+39−82
@@ -2,20 +2,19 @@
22
33 ## Status at a glance
44
5-This refactor is mostly done.
5+This refactor is complete on this branch.
66
7-The branch has already moved mini-coder toward the intended shell-first model:
7+mini-coder now follows the intended shell-first model:
88
99 - `mc-edit` exists as a dedicated helper binary
10-- shared file-edit logic was extracted under `src/internal/file-edit/`
11-- shell now exposes `mc-edit` as the preferred targeted edit path
12-- the system prompt and tool surface were simplified around shell usage
13-- model-facing local file tools have been removed or are in the process of being fully deleted from the old path
14-- hook support has been removed as part of the same cleanup
10+- shared file-edit logic lives under `src/internal/file-edit/`
11+- shell exposes `mc-edit` as the targeted edit path
12+- the system prompt and tool surface are simplified around shell usage
13+- old model-facing local file tools are removed
14+- hook support is removed
15+- `/undo` is conversation-turn undo only
1516
16-The undo cleanup has now landed too.
17-
18-`/undo` is now a conversation-turn undo only. It no longer tries to restore filesystem state, which keeps the architecture honest with the real shell + `mc-edit` edit path.
17+`/undo` no longer tries to restore filesystem state, which keeps the architecture honest with the real shell + `mc-edit` edit path.
1918
2019 ---
2120
@@ -32,8 +31,8 @@ Problems with the old approach:
3231 - failures regularly degraded into reread-and-repair loops
3332 - when that happened, shell was already the practical fallback
3433
35-The point of this refactor is **not** to improve that protocol.
36-The point is to replace it with a simpler contract that matches how models already work best:
34+The point of this refactor was **not** to improve that protocol.
35+The point was to replace it with a simpler contract that matches how models already work best:
3736
3837 - inspect with shell
3938 - edit with a narrow helper
@@ -47,7 +46,7 @@ That is why `mc-edit` exists.
4746
4847 ### Final model-facing tool surface
4948
50-The intended steady state is:
49+The steady state is:
5150
5251 - connected **MCP tools**
5352 - **`shell`**
@@ -81,7 +80,7 @@ The intended workflow is:
8180
8281 ---
8382
84-## What has landed on this branch
83+## What landed on this branch
8584
8685 ### 1. Shared file-edit internals were extracted
8786
@@ -114,7 +113,7 @@ Implemented by removing the hashline edit flow built around `replace` and `inser
114113
115114 ### 5. The local tool surface was reduced
116115
117-The branch now targets a much smaller local runtime surface centered on:
116+The local runtime surface is now centered on:
118117
119118 - `shell`
120119 - `subagent`
@@ -122,15 +121,13 @@ The branch now targets a much smaller local runtime surface centered on:
122121 - `readSkill`
123122 - optional Exa tools
124123
125-That is the right direction and should remain the end state.
126-
127124 ### 6. Hook support was removed instead of redesigned
128125
129-This cleanup is part of the refactor because hooks were tied to the old, heavier local tool story and were not worth carrying forward in the middle of this architecture change.
126+This cleanup was part of the refactor because hooks were tied to the old, heavier local tool story and were not worth carrying forward in the middle of this architecture change.
130127
131-### 7. CLI and docs cleanup has started
128+### 7. CLI and docs cleanup was completed
132129
133-Prompt text, tool rendering, help text, and docs have already been pushed toward the shell-first model, but this part still needs a final consistency pass now that undo is settled.
130+Prompt text, tool rendering, help text, and docs now consistently reflect the shell-first model and the conversation-only `/undo` behavior.
134131
135132 ---
136133
@@ -138,7 +135,7 @@ Prompt text, tool rendering, help text, and docs have already been pushed toward
138135
139136 ### 1. Shell is the primary interface for repo work
140137
141-Shell should be the default for:
138+Shell is the default for:
142139
143140 - reading files
144141 - searching
@@ -186,13 +183,13 @@ Their names and descriptions should stay concise and easy to distinguish from sh
186183
187184 ---
188185
189-## What is left to do
186+## Completion status
190187
191188 ### 1. Redesign `/undo`
192189
193190 This work is done.
194191
195-### What changed
192+#### What changed
196193
197194 Undo no longer depends on the old snapshot path.
198195 The snapshot-specific pieces were removed, including:
@@ -204,7 +201,7 @@ The snapshot-specific pieces were removed, including:
204201 `/undo` now removes only the most recent conversation turn from session history.
205202 It does not try to infer or restore filesystem state from shell-driven edits.
206203
207-### Result
204+#### Result
208205
209206 - `/undo` doesn't manage filesystem changes
210207 - snapshotting is removed from runtime code and docs
@@ -213,32 +210,11 @@ It does not try to infer or restore filesystem state from shell-driven edits.
213210
214211 ### 2. Finish the docs and help-text consistency pass
215212
216-This is partially done.
217-
218-The repo is already telling the new story in several places, and the `/undo` wording has now been updated in the core help/manpage/README surfaces, but there is still not one fully consistent source of truth yet.
219-
220-### Sweep targets
221-
222-- `mini-coder-idea.md` Note: keep it focused and in the existing idea style.
223-- `README.md`
224-- `docs/mini-coder.1.md`
225-- `docs/configs.md`
226-- `docs/custom-commands.md`
227-- `docs/custom-agents.md`
228-- `docs/skills.md`
229-- `.agents/commands/*`
230-- `.agents/agents/*`
231-- `.agents/skills/*`
232-
233-### What to check
213+This work is done.
234214
235-- mini-coder is described as shell-first
236-- `mc-edit` is clearly named as the targeted edit path
237-- removed local file tools are not described as active runtime tools
238-- removed hook support is not described anywhere
239-- `/undo` wording matches the redesigned guarantee everywhere it is documented
215+README, config/docs pages, bundled commands/skills guidance, and `mini-coder-idea.md` consistently describe the shell-first model, name `mc-edit` as the targeted edit path, and keep `/undo` scoped to conversation history only.
240216
241-### Done when
217+#### Done when
242218
243219 - docs match implementation
244220 - examples reinforce shell + `mc-edit`
@@ -249,25 +225,11 @@ The repo is already telling the new story in several places, and the `/undo` wor
249225
250226 ### 3. Final prompt, CLI, and rendering polish
251227
252-Most of this is already moving in the right direction, and the undo-specific wording cleanup is now done, but it still needs a final pass for overall consistency.
253-
254-### Areas to review
255-
256-- `src/agent/system-prompt.ts`
257-- `src/cli/tool-render.ts`
258-- `src/cli/tool-result-renderers.ts`
259-- `src/cli/commands-help.ts`
260-- `src/mcp/client.ts`
261-
262-### What to improve
228+This work is done.
263229
264-- ensure the prompt matches the final tool surface exactly
265-- keep shell guidance crisp and unambiguous
266-- make MCP descriptions more context-efficient if needed
267-- keep result previews compact and useful for shell and MCP output
268-- remove any remaining wording tied to old snapshot behavior
230+The system prompt names the final built-in tool surface explicitly, `/help` keeps `/undo` aligned with the conversation-only guarantee, MCP tool descriptions are tighter, and skill-tool call/result rendering is compact and readable.
269231
270-### Done when
232+#### Done when
271233
272234 - prompt text exactly matches runtime behavior
273235 - CLI output reflects only the remaining architecture
@@ -277,17 +239,11 @@ Most of this is already moving in the right direction, and the undo-specific wor
277239
278240 ### 4. Verify the cleanup end-to-end
279241
280-Before this refactor is considered complete, we should do one final dead-code and behavior sweep.
281-
282-### Check for
242+This work is done on this branch.
283243
284-- no runtime registration of removed local file tools
285-- no dead hashline or old edit-protocol code left behind
286-- no hook runtime/UI/doc code left behind
287-- tests aligned with the new tool surface
288-- shell + `mc-edit` workflow working in practice
244+The runtime tool set is reduced to the intended surface, the bundled hook example files were removed, and the full repo verification command passes.
289245
290-### Repo verification command
246+#### Repo verification command
291247
292248 Run:
293249
@@ -295,7 +251,7 @@ Run:
295251 bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test
296252 ```
297253
298-Status on this branch: this command passes after the undo cleanup.
254+Status on this branch: this command passes after the full shell-first cleanup.
299255
300256 ---
301257
@@ -306,7 +262,7 @@ This refactor is complete when all of the following are true:
306262 - the model-visible tool surface is shell, subagent, listSkills, readSkill, connected MCP tools, and optional Exa tools
307263 - `mc-edit` is the clear targeted edit path
308264 - the old hashline edit path is fully gone
309-- hooks are fully gone from runtime, UI, and docs
265+- hooks are fully gone from runtime, UI, and docs/examples
310266 - `/undo` is aligned with the shell-first architecture by only undoing conversation history
311267 - prompt, CLI, and docs all describe the same architecture
312268 - bundled commands/skills/examples reinforce the shell-first workflow
@@ -327,12 +283,13 @@ This effort is not trying to:
327283
328284 ## Practical conclusion
329285
330-Compared to `main`, the branch has already done the hard architectural shift: `mc-edit` exists, shell is the primary path, and the old local edit model has been largely dismantled.
286+Compared to `main`, this branch completed the hard architectural shift: `mc-edit` exists, shell is the primary path, the old local edit model is gone, hooks are gone, and `/undo` is aligned with conversation history rather than filesystem restoration.
331287
332-What remains is mostly about making the new architecture complete and honest:
288+At this point, the refactor is complete in the intended sense:
333289
334-- finish the remaining docs/help/prompt consistency pass
335-- do one final MCP/CLI polish sweep
336-- verify no stale code or messaging remains
290+- the model-visible tool surface is small and shell-first
291+- `mc-edit` is the clear targeted edit path
292+- prompt, CLI, docs, and bundled examples describe the same architecture
293+- verification passes on the branch
337294
338-That is the real endgame for this refactor.
295+Future work can build on this baseline, but the file-helper refactor itself has reached its intended end state.
docs/skills.md+2−0
@@ -2,6 +2,8 @@
22
33 Skills are reusable instruction files discovered automatically from local and global directories.
44
5+When a skill tells mini-coder how to work with files, prefer shell for inspection/search/verification and `mc-edit` from shell for targeted edits.
6+
57 - The model sees **skill metadata only** by default (name, description, source).
68 - Full `SKILL.md` content is loaded **on demand**:
79 - when explicitly requested with the runtime skill tools (`listSkills` / `readSkill`), or
mini-coder-idea.md+8−8
@@ -32,14 +32,14 @@ conventions and not introduce more specs. (`.agents` / `AGENTS.md`, while also s
3232 - Elegantly handles hitting max context size for the model. Also handles max tool calls, gracefully finishing the turn with an update from the agent
3333 - Support prompt caching via the used sdks.
3434 - Feature parity with community configs like custom agents, skill and commands.
35-- `read`, `replace`,`insert`, `create`, `shell`, and `subagent` tools for LLMs. It's imperitive that these are easy to use and actually reduce the friction during these tasks for the LLMs
36-- read/write tools are streamlined, easy to use and rely on hashline editting pattern.
35+- Shell-first tool surface for LLMs: `shell`, `subagent`, `listSkills`, and `readSkill`, plus connected MCP tools. Keep the core surface small and easy to use so it actually reduces friction for the LLMs.
36+- File work should follow a simple flow: inspect with shell, mutate with `mc-edit`, verify with shell.
37+- `mc-edit` should stay narrow and reliable: exact-text edits only, deterministic failures on stale or ambiguous state, machine-friendly output.
3738 - Optional `webSearch` and `webContent` tools when `EXA_API_KEY` is set.
3839 - `subagent` tool spawns a fresh `mc` subprocess in one shot mode.
39-- tool hooks support for supported built-in tools
4040 - Commands in CLI prompt:
4141 - `/model` (alias `/models`) 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.
42- - `/undo` removes the last turn from conversation history.
42+ - `/undo` removes the last turn from conversation history, it does not restore filesystem state.
4343 - `/reasoning` toggles display of model reasoning output.
4444 - `/context` configures context pruning and tool-result caps.
4545 - `/cache` toggles prompt caching globally; sub-commands configure provider-specific caching (`/cache openai <in_memory|24h>`, `/cache gemini <off|cachedContents/...>`).
@@ -57,9 +57,9 @@ conventions and not introduce more specs. (`.agents` / `AGENTS.md`, while also s
5757 - Use pi and claude code as visual inspirations.
5858 - Banner at app start, show found configs and context files
5959 - history log (like a terminal output scrolls away, pushing the input prompt down)
60- - Read tool show the tool call with args fomatted for output
61- - Edit tools show the diff applied
62- - Shell tools show the command called and their output
60+ - Skill tools show compact metadata-oriented output
61+ - Shell tool shows the command called and its output
62+ - MCP tools stay clearly distinguishable from shell work
6363 - status bar like prompt, with current model/provider/session/git branch/active agent/thinking effort/context usage/token input/token output
6464 - some prompt colored animation when a turn is processing. Needs to be carefully done, so it shows correctly in wait times and with clear labels
6565
@@ -80,6 +80,6 @@ Core modules:
8080 - `llm-api`: Provides the api to intereact with the provider and process the full conversation turn + tool calling.
8181 - `cli`: Output/UI, with logical separated subfolder: user input/output and ui/etc..
8282 - `agent`: Main agent implementation
83-- `tools`: local filesystem, shell, subagent, and web/search helpers
83+- `tools`: shell, subagent, skill, and web/search helpers
8484 - `session`: sqlite-backed sessions, settings, model info, and MCP server storage
8585 - `mcp`: handles connecting to mcp servers
src/agent/system-prompt.ts+1−1
@@ -86,7 +86,7 @@ export function buildSystemPrompt(
8686 const localContext = loadLocalContextFile(cwd);
8787 const cwdDisplay = tildePath(cwd);
8888 let prompt = `You are mini-coder, a small and fast CLI coding agent.
89-You have access to shell commands, skill-loading tools, subagents, connected MCP tools, and optional web tools.
89+You have access to shell, subagent, listSkills, readSkill, connected MCP tools, and optional web tools.
9090
9191 Current working directory: ${cwdDisplay}
9292 Current date/time: ${sessionTimeAnchor}
src/cli/commands-help.ts+1−1
@@ -13,7 +13,7 @@ export function renderHelpCommand(
1313
1414 const cmds: [string, string][] = [
1515 ["/model [id]", "list or switch models (fetches live list)"],
16- ["/undo", "remove the last conversation turn"],
16+ ["/undo", "remove the last conversation turn (no filesystem revert)"],
1717 ["/reasoning [on|off]", "toggle display of model reasoning output"],
1818 ["/context [prune|cap]", "configure context pruning and tool-result caps"],
1919 [
src/cli/tool-render.test.ts+25−0
@@ -45,6 +45,12 @@ describe("buildToolCallLine", () => {
4545 expect(line).toContain("$");
4646 expect(line).toContain("shell");
4747 });
48+
49+ test("formats readSkill calls with the requested skill name", () => {
50+ const line = buildToolCallLine("readSkill", { name: "deploy" });
51+ expect(line).toContain("read skill");
52+ expect(line).toContain("deploy");
53+ });
4854 });
4955
5056 describe("renderToolResult", () => {
@@ -69,4 +75,23 @@ describe("renderToolResult", () => {
6975 expect(plain).not.toContain("stderr (1 lines)");
7076 expect(plain).not.toContain("│ boom");
7177 });
78+
79+ test("renders compact listSkills previews", () => {
80+ captureStdout();
81+
82+ renderToolResult(
83+ "listSkills",
84+ {
85+ skills: [
86+ { name: "deploy", description: "Deploy safely", source: "local" },
87+ { name: "release", description: "Ship releases", source: "global" },
88+ ],
89+ },
90+ false,
91+ );
92+
93+ const plain = stripAnsi(stdout);
94+ expect(plain).toContain("deploy · local · Deploy safely");
95+ expect(plain).toContain("release · global · Ship releases");
96+ });
7297 });
src/cli/tool-render.ts+11−0
@@ -5,6 +5,8 @@ import { renderToolResultByName } from "./tool-result-renderers.ts";
55 function toolGlyph(name: string): string {
66 if (name === "shell") return G.run;
77 if (name === "subagent") return G.agent;
8+ if (name === "readSkill") return G.read;
9+ if (name === "listSkills") return G.search;
810 if (name.startsWith("mcp_")) return G.mcp;
911 return G.info;
1012 }
@@ -29,6 +31,15 @@ export function buildToolCallLine(name: string, args: unknown): string {
2931 return `${G.run} ${shortCmd}`;
3032 }
3133
34+ if (name === "listSkills") {
35+ return `${G.search} ${c.dim("list skills")}`;
36+ }
37+
38+ if (name === "readSkill") {
39+ const skillName = typeof a.name === "string" ? a.name : "";
40+ return `${G.read} ${c.dim("read skill")}${skillName ? ` ${skillName}` : ""}`;
41+ }
42+
3243 if (name.startsWith("mcp_")) {
3344 return `${G.mcp} ${c.dim(name)}`;
3445 }
src/cli/tool-result-renderers.ts+33−0
@@ -114,6 +114,38 @@ function renderSubagentResult(result: unknown): boolean {
114114 return true;
115115 }
116116
117+function renderListSkillsResult(result: unknown): boolean {
118+ const r = result as {
119+ skills?: Array<{
120+ name?: string;
121+ description?: string;
122+ source?: "local" | "global";
123+ }>;
124+ };
125+ if (!Array.isArray(r?.skills)) return false;
126+ if (r.skills.length === 0) {
127+ writeln(` ${G.info} ${c.dim("no skills")}`);
128+ return true;
129+ }
130+
131+ for (const skill of r.skills.slice(0, 6)) {
132+ const name = skill.name ?? "(unknown)";
133+ const source = skill.source ?? "unknown";
134+ const description = skill.description?.trim();
135+ const descPart = description
136+ ? ` ${c.dim("·")} ${c.dim(description.length > 60 ? `${description.slice(0, 57)}…` : description)}`
137+ : "";
138+ writeln(
139+ ` ${G.info} ${name} ${c.dim("·")} ${c.dim(source)}${descPart}`,
140+ );
141+ }
142+
143+ if (r.skills.length > 6) {
144+ writeln(` ${c.dim(`+${r.skills.length - 6} more skills`)}`);
145+ }
146+ return true;
147+}
148+
117149 function renderReadSkillResult(result: unknown): boolean {
118150 const r = result as {
119151 skill?: {
@@ -215,6 +247,7 @@ function renderMcpResult(result: unknown): boolean {
215247 const TOOL_RESULT_RENDERERS: Readonly<Record<string, ToolResultRenderer>> = {
216248 shell: renderShellResult,
217249 subagent: renderSubagentResult,
250+ listSkills: renderListSkillsResult,
218251 readSkill: renderReadSkillResult,
219252 webSearch: renderWebSearchResult,
220253 webContent: renderWebContentResult,
src/mcp/client.ts+1−1
@@ -74,7 +74,7 @@ export async function connectMcpServer(
7474
7575 const tools: ToolDef[] = mcpTools.map((t) => ({
7676 name: `mcp_${config.name}_${t.name}`,
77- description: `[MCP:${config.name}] ${t.description ?? t.name}`,
77+ description: `MCP ${config.name}: ${t.description?.trim() || t.name}`,
7878 // Use the server's declared JSON schema directly
7979 schema: t.inputSchema,
8080 execute: async (input: unknown) => {