@@ -0,0 +1,108 @@
1+## Core idea: treat this as the source of truth for the design and implementation.
2+
3+mini-coder - `mc`
4+
5+An augmented shell-prompt coding agent: small, fast, and out of the way.
6+
7+### Inspirations
8+
9+- Pi agent: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent
10+- Claude Code: https://claude.com/product/claude-code
11+- Codex: https://github.com/openai/codex
12+- Opencode: https://opencode.ai/
13+
14+### Philosophy
15+
16+**Performance first, style second.**
17+
18+Core features must be correct and fast before adding new ones.
19+Community-oriented: support `AGENTS.md` and `agentskills.io` specs, and do not introduce new config formats.
20+
21+### Features
22+
23+- Auto-discover and load community config standards on startup:
24+ - `AGENTS.md` -> https://agents.md/
25+ - Skills -> https://agentskills.io/client-implementation/adding-skills-support
26+
27+- Auto-discovery of providers via env vars (example: `OPENCODE_API_KEY`) or local servers (example: Ollama).
28+ - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. support OpenAI (`openai` uses the Codex / ChatGPT Plus/Pro flow) and Anthropic (Claude Max/Pro). Use Pi coding agent source code as a reference for this.
29+ - `/model` picks a model from connected providers. The selection persists across sessions and uses an interactive selector.
30+ - `/effort [args]` sets the model effort.
31+
32+- Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
33+ - Auto-discover keys like `EXA_AI_API_KEY` to auto-connect to their MCP server.
34+ - `/mcp` lists, adds, and removes MCP servers. Servers are stored in SQLite.
35+
36+- Session management and commands to create, resume, and list sessions using a local SQLite file.
37+ - `/session` interactively manages sessions. Sessions are scoped to the CWD to avoid cross-project session pollution.
38+ - `/new` starts a new session with an empty message history, clears the screen, and redraws the banner.
39+ - `/fork` forks the conversation into a new session.
40+ - `/undo` removes the last turn from history (does not restore filesystem).
41+ - Sessions should also track errors and logs in a separate table from messages, mostly for debugging purposes, and should not affect the user session.
42+
43+- Enriched user prompt:
44+ - Rich line editing, history, and paste support. Enter submits; Shift+Enter adds new lines.
45+ - Reference skills from the working directory and global configs with `/skill:...` in the prompt input, plus interactive autocomplete for skills to include in the prompt.
46+ - 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. `Ctrl+C` and `Ctrl+D` (EOF) gracefully exit. `Ctrl+Z` suspends/backgrounds the process and returns the user to the shell prompt.
47+ - Reference files with `@`, which embeds a file path into the prompt and autocompletes interactively. It also supports adding images to the prompt if the referenced file is an image.
48+ - On error, display a one-line summary to the user, and return to the input prompt.
49+
50+- Context handling:
51+ - Stop with a conversation summary at max context. This must not break prompt caching.
52+ - No max steps or tool call limits — user can interrupt.
53+ - Clear, accurate token and cost tracking. Use `models.dev` as the source for model metadata and costs.
54+
55+- Minimal tool surface: `shell`, `edit`, `listSkills`, `readSkill`.
56+ - Inspect with `shell` -> mutate with `edit` -> verify with `shell`.
57+ - Auto-truncate large shell outputs for the LLM to avoid context explosions.
58+ - `edit`: exact-text edits only, deterministic failures on stale/ambiguous state. Based on industry standard edit/apply patch tools.
59+ - A single system prompt that works across all supported models (no provider-specific branches). It is constructed based on our inspirations and provider resources such as:
60+ - https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide
61+ - https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
62+
63+- Other commands in the CLI prompt:
64+ - `/reasoning` toggles display of model reasoning output.
65+ - `/verbose` toggles output truncation. When off, large outputs keep the start/end sections and truncate the middle. This is a UI-only visibility concern.
66+
67+- Internal skill (hidden from the user) that teaches the agent how to use minicoder and help the user configure it and use it well. Should be compliant with the agentskills.io specification.
68+
69+- App data folder in `~/.config/mini-coder/` in linux, or the respective app data folder in other OS. It includes sqlite db file and logs.
70+
71+### UI/Output
72+
73+- Use the 16 ANSI colors so coloring is always inherited from the terminal theme (https://jvns.ca/blog/2024/10/01/terminal-colours/). Keep a `theme.json` file in the app data directory with the palette used so users can customize colors, italics, bold, and glyphs.
74+- Never use ambiguous-width characters; stick with single-width Unicode characters for maximum cross-terminal compatibility.
75+- Minimal banner at app start showing loaded context files, skills, connected providers, and configured MCP servers.
76+- Scrolling conversation log (new output pushes the input prompt down):
77+ - Skill tools: one-line name + description, no body content.
78+ - Shell tool: the command, then its stdout/stderr.
79+ - Edit tool: a clean diff of the change applied.
80+ - MCP tools: prefixed with server name to distinguish from built-in tools.
81+- Status bar below the input prompt showing model, model effort, provider, session ID, git branch, context usage %, and concise token and cost counts.
82+- Clear boundary around the user input area. The area expands as new lines are added.
83+- Inline spinner with an activity label (e.g. "thinking", "running shell") when a turn is in flight for all actions and while waiting for the LLM to complete its work. It must not interfere with scrollback or leave artifacts on interrupt.
84+
85+### Tech stack
86+
87+- Bun.js for runtime and package management. https://bun.com/docs
88+- Multiprovider support via https://ai-sdk.dev/docs/introduction or by re-using Pi's: https://github.com/badlogic/pi-mono/tree/main/packages/ai (this looks better, it saves us a lot of headaches by already having oauth baked in.)
89+- MCP via the official SDK: `@modelcontextprotocol/sdk`
90+- Colored output with https://github.com/sindresorhus/yoctocolors - limited but fast.
91+- Our own helper packages: `@yoctomarkdown` for streamed Markdown rendering and `@yoctoselect` for a simple, fully featured interactive selector.
92+- sqlite for sql storage
93+
94+### Repo structure
95+
96+We want to break everything down into workspaces as internal packages. This will force us to have clear boundaries for each package and improve maintainability.
97+
98+Suggested core packages:
99+
100+- `terminal-ui`: the UI implementation and all output concerns, isolated from the rest of the project so we can more easily support other output formats going forward.
101+- `agent`: the agent implementation, which is the core of the project.
102+- `providers`: the unified provider implementation/sdk usage.
103+- `storage`: implements the storage interface using SQLite for persistence.
104+- `types`: shared types.
105+
106+### Extensibility (NOT IN SCOPE! DO NOT IMPLEMENT)
107+
108+Users should be able to extend mini-coder easily with a plugin format. This should enable custom commands, providers, context handling, etc. While this is currently out of scope and not fully defined, it should be kept in mind during development so we avoid unnecessary complexity when we do add it.