@@ -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.