xonecas.io
64875
Mc

mini-coder / commit 51586e9

feat: repo docs maintenance

xonecas2026-03-20 51586e9f1c44344c0050c00f437f9860755f0616 parent 8969dbf

5 files changed

.agents/skills/audit/SKILL.md+3−3
@@ -3,11 +3,11 @@ name: audit
33 description: Full codebase audit — code review, multi-provider UI testing, and combined report.
44 ---
55
6-Run a complete audit of the mini-coder implementation. Use `mini-coder-idea.md` and `TODO.md` as source of truth throughout.
6+Run a complete audit of the mini-coder implementation.
77
88 ## Phase 1 — Code & Architecture Review
99
10-Audit the codebase against `mini-coder-idea.md`:
10+Audit the codebase against the core idea:
1111
1212 - Question design choices and rethink as needed while staying compliant with the original idea.
1313 - Employ KISS, DRY, and YAGNI — no surprise additions or eager optimizations.
@@ -45,7 +45,7 @@ Write `AUDIT-REPORT.md` in the repo root with these sections:
4545
4646 - **Summary** — how you tested and what you found.
4747 - **Code & Architecture** — correctness issues, KISS, DRY, and YAGNI violations, idea misalignment.
48-- **UI/UX Alignment** — comparison of actual output vs mini-coder-idea.md expectations across providers.
48+- **UI/UX Alignment** — comparison of actual output vs the core idea's expectations across providers.
4949 - **Recommendations** — split into immediate bugs, code changes, and polish items.
5050
5151 Don't just recite the todo items back to the user, report on the audit itself.
AGENTS.md+95−1
@@ -1,7 +1,6 @@
11 # Mini Coder repo for agents:
22
33 - App data folder is in `~/.config/mini-coder/`. It includes sqlite db file and logs.
4-- Core idea is in [mini-coder-idea.md](mini-coder-idea.md); READ IT. This file is managed by the user, don't edit unless asked to by the user. Treat this as the source of truth for the design/implementation.
54 - README.md is cosmetic for users, don't edit unless asked to.
65 - Write minimal tests, focused on our code's logic. Never test dependencies. Never use mocks or stubs.
76 - Keep the repo pristine: no failing tests, no lint, no build issues, no `ignore`-style comments. No failing hooks.
@@ -14,3 +13,98 @@
1413 - Don't make random test files, if you need to test something, write a propper unit test.
1514 - If you make temp files, clean them up when you are done.
1615 - Use Conventional Commits formatting for commit messages. When you commit, include the whole diff unless told otherwise.
16+- Create or reuse the `TODO.md` file to track your progress in long tasks. Remove completed items, keep it clean and concise. Track it in git.
17+
18+## Core idea, treat this as the source of truth for the design/implementation.
19+
20+mini-coder - `mc`
21+
22+A coding agent via a augmented shell prompt, small and fast that doesn't get in the way
23+
24+### Inpirations:
25+
26+- Pi agent: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent amazing tool, like a swiss army knife of coding agents.
27+- Claude Code: https://claude.com/product/claude-code clean UI, propertary software
28+- Codex: https://github.com/openai/codex Powerful and open source, focused on heavy open-ai integration
29+- Opencode: https://opencode.ai/ The open source standard. Similar to oh-my-pi but with a different aesthetic
30+
31+### Philosophy:
32+
33+**Fast and performant**, instant feedback shell like output. Performance first style second.
34+
35+Very focused on dev flow, simple setup steps and fast to coding.
36+Elegant output that focus on the conversation with the agent and their actions. Ensure an accurate cronological conversation log that is very readable for the user. Keep a visible hierchy of actions -> results and assistant reasoning and responses.
37+Accurate and reliable and fast core set of features.
38+Community oriented, all of the inspirations have their own dotfile format, try to follow the existing
39+conventions and not introduce more specs.
40+
41+### Features:
42+
43+- We want to do our best to support and autodiscover community config standards:
44+ - AGENTS.md -> https://agents.md/
45+ - CLAUDE.md (same as AGENTS.md)
46+ - Skills -> https://agentskills.io/client-implementation/adding-skills-support (and https://agentskills.io/client-implementation/adding-skills-support.md)
47+ - Claude skills too. They claim to follow the spec, we should only need to discover them too.
48+
49+- Auto discovery of providers via ENV (Example: OPENCODE_API_KEY), or local servers (Example: ollama)
50+ - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. Currently supports Anthropic. (Both pi and opencode support this too)
51+ - `/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. Must have autocomplete support for ease of use when changing models
52+
53+- Session management and command to create new/resume/list with local sqlite file.
54+ - `/session` command to interactively manage sessions as well as cli flags.
55+ - `/new` starts a new session with clean context. Clean UI and fresh session display
56+
57+- Enriched user prompt:
58+ - Rich line editing/history/image paste. Enter submits.
59+ - Seamless shell integration with `!` in prompt input. Runs command in subprocess and sends the output to the llm as user message.
60+ - Reference skills from the working directory and global configs with `/` in prompt input, plus autocomplete for skills to include in the prompt.
61+ - 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 forcefully. `ctrl+d` (EOF) gracefully exits.
62+ - Image support in prompt input, including pasted image data URLs and pasted image file paths.
63+ - Shell like autocomplete for filepaths, `@` embeds a file into the prompt and autocompletes filepaths
64+
65+- Context handling:
66+ - Elegantly handles hitting max context size for the model using regular per step pruning. Stops with a conversation summary if max context is reached.
67+ - No max steps or max tool calls. user can interrupt, this is not needed.
68+ - Support prompt caching via the used sdks.
69+ - Rolling context pruning with a balanced default. (Must not break caching!)
70+ - Clear and accurate token tracking.
71+ - Recover from errors returning the user to the prompt with clear messaging
72+ - `/undo` removes the last turn from conversation history, it does not restore filesystem state.
73+
74+- Shell-first tool surface for LLMs: `shell`, `listSkills`, and `readSkill`, plus connected MCP tools and optional web tools when configured. Keep the core surface small and easy to use so it actually reduces friction for the LLMs.
75+ - File work should follow a simple flow: inspect with shell, mutate with `mc-edit`, verify with shell.
76+ - Large shell outputs should be truncated automatically for the llm, to avoid context explosions and encourage targetted reads.
77+ - `mc-edit` should stay narrow and reliable: exact-text edits only, deterministic failures on stale or ambiguous state, diff and machine-friendly output while staying human readable.
78+ - Optional `webSearch` and `webContent` tools when `EXA_API_KEY` is set.
79+ - Cross model system prompt with clear descriptions of the expected dev flow and guidance as a code agent focused on shell first.
80+
81+- Other Commands in CLI prompt:
82+ - `/reasoning` toggles display of model reasoning output.
83+ - `/verbose` toggles output truncation. Tuncates large outputs keeping start and end sections and truncating the rest when verbose is off. This controls truncation for the user output, it's a visibility UI concern
84+ - `/review` reviews recent changes via a global custom skill installed at app start (`~/.agents/skills/review.md`), and can be customized or shadowed locally.
85+
86+- Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
87+ - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
88+
89+### UI/Output
90+
91+- Use the 16 ANSII colors so the coloring is allways inherited from the terminal theme (https://jvns.ca/blog/2024/10/01/terminal-colours/)
92+- Use pi and claude code as visual inspirations.
93+- Banner at app start, show found configs and context files
94+- history log (like a terminal output scrolls away, pushing the input prompt down)
95+ - Skill tools show compact metadata-oriented output
96+ - Shell tool shows the command called and its output
97+ - MCP tools stay clearly distinguishable from shell work
98+- status bar like prompt, with current model/provider/session/git branch/thinking effort/context usage/token input/token output information grouped logically and human readable.
99+- 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
100+
101+### Tech stack
102+
103+- All things Bun.js, runtime, package manager. https://bun.com/docs
104+- Multiprovider support via https://ai-sdk.dev/docs/introduction
105+- Colored output with https://github.com/sindresorhus/yoctocolors limitted but fast!
106+
107+### Repo structure
108+
109+Clean separation of concerns, use modules to organize the app. Group logical features together for best browsability and readability of the code. Use subdirectories to group files logically.
110+No mocked/offline-servers type of tests. Focused tests on _our_ logic. Do not test our dependencies.
KNOWN_ISSUES.md+23−0
@@ -0,0 +1,23 @@
1+# KNOWN ISSUES
2+
3+## Bugs
4+
5+- CTRL+d hangs sometimes and doesn't exit.
6+- `supportsThinking()` trusts models.dev flag too broadly — sends adaptive thinking to models that reject it (e.g. `claude-haiku-4-5` via Zen returns 400).
7+- AI SDK expands `claude-3-5-haiku` → dated variant that Zen doesn't serve (404).
8+- Shell tool max-timeout leaves the parent terminal in a broken state.
9+- MiniMax sends empty text deltas in one-shot — renders as blank lines.
10+- Double prompt glyph after ESC — `turn-complete` newline + input loop prompt collide.
11+- Truncated tool commands cut mid-argument (e.g. `--new '{…`). Truncate at argument boundaries instead.
12+
13+## Features
14+
15+- Conversation summary on max context instead of just an error with `/new` suggestion.
16+- Derive `maxOutputTokens` from model info instead of hardcoding 16384.
17+- `/_debug` hidden command — snapshot recent logs/db into a report in cwd.
18+
19+## Refactors
20+
21+- Consolidate truncation helpers across cli modules into `cli/truncate.ts`.
22+- Consolidate `parseSkillFrontmatter` (skills.ts) with `parseFrontmatter` (frontmatter.ts).
23+- Status bar: merge model + thinking effort into one field, drop `showReasoning` (already in banner).
TODO.md+1−23
@@ -1,23 +1 @@
1-# TODO
2-
3-## Bugs
4-
5-- CTRL+d hangs sometimes and doesn't exit.
6-- `supportsThinking()` trusts models.dev flag too broadly — sends adaptive thinking to models that reject it (e.g. `claude-haiku-4-5` via Zen returns 400).
7-- AI SDK expands `claude-3-5-haiku` → dated variant that Zen doesn't serve (404).
8-- Shell tool max-timeout leaves the parent terminal in a broken state.
9-- MiniMax sends empty text deltas in one-shot — renders as blank lines.
10-- Double prompt glyph after ESC — `turn-complete` newline + input loop prompt collide.
11-- Truncated tool commands cut mid-argument (e.g. `--new '{…`). Truncate at argument boundaries instead.
12-
13-## Features
14-
15-- Conversation summary on max context instead of just an error with `/new` suggestion.
16-- Derive `maxOutputTokens` from model info instead of hardcoding 16384.
17-- `/_debug` hidden command — snapshot recent logs/db into a report in cwd.
18-
19-## Refactors
20-
21-- Consolidate truncation helpers across cli modules into `cli/truncate.ts`.
22-- Consolidate `parseSkillFrontmatter` (skills.ts) with `parseFrontmatter` (frontmatter.ts).
23-- Status bar: merge model + thinking effort into one field, drop `showReasoning` (already in banner).
1+Nothing :)
mini-coder-idea.md+0−91
@@ -1,91 +0,0 @@
1-# mini-coder
2-
3-A coding agent via a augmented shell prompt, small and fast that doesn't get in the way
4-
5-## Inpirations:
6-
7-- Pi agent: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent amazing tool, like a swiss army knife of coding agents.
8-- Claude Code: https://claude.com/product/claude-code clean UI, propertary software
9-- Codex: https://github.com/openai/codex Powerful and open source, focused on heavy open-ai integration
10-- Opencode: https://opencode.ai/ The open source standard. Similar to oh-my-pi but with a different aesthetic
11-
12-## Philosophy:
13-
14-**Fast and performant**, instant feedback shell like output. Performance first style second.
15-
16-Very focused on dev flow, simple setup steps and fast to coding.
17-Elegant output that focus on the conversation with the agent and their actions. Ensure an accurate cronological conversation log that is very readable for the user. Keep a visible hierchy of actions -> results and assistant reasoning and responses.
18-Accurate and reliable and fast core set of features.
19-Community oriented, all of the inspirations have their own dotfile format, try to follow the existing
20-conventions and not introduce more specs.
21-
22-## Features:
23-
24-- We want to do our best to support and autodiscover community config standards:
25- - AGENTS.md -> https://agents.md/
26- - CLAUDE.md (same as AGENTS.md)
27- - Skills -> https://agentskills.io/client-implementation/adding-skills-support (and https://agentskills.io/client-implementation/adding-skills-support.md)
28- - Claude skills too. They claim to follow the spec, we should only need to discover them too.
29-
30-- Auto discovery of providers via ENV (Example: OPENCODE_API_KEY), or local servers (Example: ollama)
31- - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. Currently supports Anthropic. (Both pi and opencode support this too)
32- - `/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. Must have autocomplete support for ease of use when changing models
33-
34-- Session management and command to create new/resume/list with local sqlite file.
35- - `/session` command to interactively manage sessions as well as cli flags.
36- - `/new` starts a new session with clean context. Clean UI and fresh session display
37-
38-- Enriched user prompt:
39- - Rich line editing/history/image paste. Enter submits.
40- - Seamless shell integration with `!` in prompt input. Runs command in subprocess and sends the output to the llm as user message.
41- - Reference skills from the working directory and global configs with `/` in prompt input, plus autocomplete for skills to include in the prompt.
42- - 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 forcefully. `ctrl+d` (EOF) gracefully exits.
43- - Image support in prompt input, including pasted image data URLs and pasted image file paths.
44- - Shell like autocomplete for filepaths, `@` embeds a file into the prompt and autocompletes filepaths
45-
46-- Context handling:
47- - Elegantly handles hitting max context size for the model using regular per step pruning. Stops with a conversation summary if max context is reached.
48- - No max steps or max tool calls. user can interrupt, this is not needed.
49- - Support prompt caching via the used sdks.
50- - Rolling context pruning with a balanced default. (Must not break caching!)
51- - Clear and accurate token tracking.
52- - Recover from errors returning the user to the prompt with clear messaging
53- - `/undo` removes the last turn from conversation history, it does not restore filesystem state.
54-
55-- Shell-first tool surface for LLMs: `shell`, `listSkills`, and `readSkill`, plus connected MCP tools and optional web tools when configured. Keep the core surface small and easy to use so it actually reduces friction for the LLMs.
56- - File work should follow a simple flow: inspect with shell, mutate with `mc-edit`, verify with shell.
57- - Large shell outputs should be truncated automatically for the llm, to avoid context explosions and encourage targetted reads.
58- - `mc-edit` should stay narrow and reliable: exact-text edits only, deterministic failures on stale or ambiguous state, diff and machine-friendly output while staying human readable.
59- - Optional `webSearch` and `webContent` tools when `EXA_API_KEY` is set.
60- - Cross model system prompt with clear descriptions of the expected dev flow and guidance as a code agent focused on shell first.
61-
62-- Other Commands in CLI prompt:
63- - `/reasoning` toggles display of model reasoning output.
64- - `/verbose` toggles output truncation. Tuncates large outputs keeping start and end sections and truncating the rest when verbose is off. This controls truncation for the user output, it's a visibility UI concern
65- - `/review` reviews recent changes via a global custom skill installed at app start (`~/.agents/skills/review.md`), and can be customized or shadowed locally.
66-
67-- Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
68- - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
69-
70-## UI/Output
71-
72-- Use the 16 ANSII colors so the coloring is allways inherited from the terminal theme (https://jvns.ca/blog/2024/10/01/terminal-colours/)
73-- Use pi and claude code as visual inspirations.
74-- Banner at app start, show found configs and context files
75-- history log (like a terminal output scrolls away, pushing the input prompt down)
76- - Skill tools show compact metadata-oriented output
77- - Shell tool shows the command called and its output
78- - MCP tools stay clearly distinguishable from shell work
79-- status bar like prompt, with current model/provider/session/git branch/thinking effort/context usage/token input/token output information grouped logically and human readable.
80-- 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
81-
82-## Tech stack
83-
84-- All things Bun.js, runtime, package manager. https://bun.com/docs
85-- Multiprovider support via https://ai-sdk.dev/docs/introduction
86-- Colored output with https://github.com/sindresorhus/yoctocolors limitted but fast!
87-
88-## Repo structure
89-
90-Clean separation of concerns, use modules to organize the app. Group logical features together for best browsability and readability of the code. Use subdirectories to group files logically.
91-No mocked/offline-servers type of tests. Focused tests on _our_ logic. Do not test our dependencies.