xonecas.io
64875
Mc

mini-coder / commit 45aadcd

docs: add spec and clean up conflicting legacy docs

xonecas2026-04-01 45aadcdd0021ef3ead9d965ece2809b7b8397e26 parent 6b5d3a7

8 files changed

.gitignore+1−1
@@ -10,4 +10,4 @@ bun.lock
1010 package-lock.json
1111 .DS_Store
1212 logs/
13-
13+.codex
AGENTS.md+0−87
@@ -18,90 +18,3 @@
1818 - Before committing, run `git status` and ensure every modified and untracked file produced during the session is included. Do not leave files behind.
1919 - Use Conventional Commits formatting for commit messages.
2020 - Before committing code changes, review the diff with the user and get approval for the commit. Treat direct user requests to commit or to do repository tasks as approval.
21-
22-## Core idea, treat this as the source of truth for the design/implementation.
23-
24-mini-coder - `mc`
25-
26-An augmented shell prompt coding agent — small, fast, stays out of the way.
27-
28-### Inspirations:
29-
30-- Pi agent: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent
31-- Claude Code: https://claude.com/product/claude-code
32-- Codex: https://github.com/openai/codex
33-- Opencode: https://opencode.ai/
34-
35-### Philosophy:
36-
37-**Performance first, style second.** Instant feedback, shell-like output.
38-
39-Focused on dev flow — minimal setup, fast to coding.
40-Output is a scrolling chronological log, append only with full streaming visibility to the user: actions → results → reasoning → responses. No redraws, no clearing — append-only like a terminal. Exception: `/new` clears the screen for a fresh start.
41-Core features must be correct and fast before adding new ones.
42-Community oriented — support AGENTS.md and agentskills.io specs, don't introduce new config formats.
43-
44-### Features:
45-
46-- Autodiscover and load community config standards on startup:
47- - AGENTS.md / CLAUDE.md → https://agents.md/
48- - Skills (`.agents/skills/` and `.claude/skills/`) → https://agentskills.io/client-implementation/adding-skills-support
49-
50-- Auto discovery of providers via ENV (Example: OPENCODE_API_KEY), or local servers (Example: ollama)
51- - `/login` shows OAuth login status. `/login <provider>` starts browser-based OAuth login. `/logout <provider>` clears saved tokens. Currently supports OpenAI (`openai` uses the Codex / ChatGPT Plus/Pro flow). Anthropic support was removed to comply to their TOS, we can't impersonate claude.
52- - `/model` (alias `/models`) picks a model from connected providers, including thinking effort if supported. Selection persists across sessions with autocomplete.
53-
54-- Session management and command to create new/resume/list with local sqlite file.
55- - `/session` command to interactively manage sessions as well as cli flags.
56- - `/new` starts a new session with empty message history, clears the screen, and redraws the banner.
57-
58-- Enriched user prompt:
59- - Rich line editing/history/image paste. Enter submits.
60- - Seamless shell integration with `!` in prompt input. Runs command in subprocess and sends the output to the llm as user message.
61- - Reference skills from the working directory and global configs with `/` in prompt input, plus autocomplete for skills to include in the prompt.
62- - 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.
63- - Image support in prompt input, including pasted image data URLs and pasted image file paths.
64- - Shell like autocomplete for filepaths, `@` embeds a file into the prompt and autocompletes filepaths
65-
66-- Context handling:
67- - Rolling context pruning per step; stops with a conversation summary at max context. Must not break prompt caching.
68- - No max steps or tool call limits — user can interrupt.
69- - Clear, accurate token tracking.
70- - On error, log it, display a one-line summary to the user, and return to the input prompt.
71- - `/undo` removes the last turn from history (does not restore filesystem).
72-
73-- Shell-first tool surface: `shell`, `listSkills`, `readSkill`, plus connected MCP tools and optional web tools (`EXA_API_KEY`). Keep it small.
74- - Inspect with shell → mutate with `mc-edit` → verify with shell.
75- - Auto-truncate large shell outputs for the LLM to avoid context explosions.
76- - `mc-edit`: exact-text edits only, deterministic failures on stale/ambiguous state.
77- - Single system prompt that works across all supported models (no provider-specific branches).
78-
79-- Other Commands in CLI prompt:
80- - `/reasoning` toggles display of model reasoning output.
81- - `/verbose` toggles output truncation. When off, large outputs keep start/end sections and truncate the middle. UI-only visibility concern.
82-
83-- Connect to MCP servers over Streamable HTTP / SSE fallback or stdio.
84- - `/mcp` list/add/remove mcp servers. servers are stored in sqlite
85-
86-### UI/Output
87-
88-- Use the 16 ANSI colors so coloring is always inherited from the terminal theme (https://jvns.ca/blog/2024/10/01/terminal-colours/)
89-- Use pi and claude code as visual inspirations.
90-- Banner at app start listing discovered AGENTS.md files, context files, and provider status.
91-- Append-only scrolling log (new output pushes the input prompt down, nothing is redrawn):
92- - Skill tools: one-line name + description, no body content.
93- - Shell tool: the command, then its stdout/stderr.
94- - MCP tools: prefixed with server name to distinguish from built-in tools.
95-- Status bar above the input prompt showing: model, provider, session id, git branch, thinking effort, context %, input tokens, output tokens.
96-- Inline spinner with a label (e.g. "thinking", "running shell") while waiting for LLM or tool responses. Must not interfere with scrollback or leave artifacts on interrupt.
97-
98-### Tech stack
99-
100-- All things Bun.js, runtime, package manager. https://bun.com/docs
101-- Multiprovider support via https://ai-sdk.dev/docs/introduction
102-- Colored output with https://github.com/sindresorhus/yoctocolors — limited but fast.
103-
104-### Repo structure
105-
106-One directory per module (e.g. `cli/`, `agent/`, `session/`, `tools/`, `llm-api/`). Each directory owns its types, logic, and tests — no cross-module circular imports.
107-Tests live next to the code they test (`foo.test.ts` beside `foo.ts`). No mock servers, no dependency tests — test only our logic.
TODO.md+0−2
@@ -1,3 +1 @@
11 # mini-coder TODO
2-
3-_No open items._
docs/KNOWN_ISSUES.md+6−0
@@ -8,6 +8,12 @@
88 - MCP runtime state is not reconciled live: removing a server only deletes its DB row, and re-adding/updating can leave stale or duplicate live MCP tools until `/new` or a session switch reconnects everything.
99 - Switching or resuming a session does not update the active working directory. Shell passthrough, file refs, prompt context, and status UI keep using the process startup `cwd`, so a session from another repo can run against the wrong project.
1010 - SQLite schema version mismatches rotate the existing DB aside and start from a fresh empty DB instead of migrating or warning clearly. Upgrades can make session history, MCP config, OAuth state, and cached model info appear lost unless the user manually recovers the backup.
11+- Persist `/model` changes to the session row immediately so resume/switch sees the new model even before another turn completes.
12+- Stop trimming submitted prompt text in interactive and piped flows; preserve leading indentation and trailing newlines while keeping blank-input detection.
13+- Rebuild/reset activated skill state on `/undo` and resume so `readSkill` matches actual remaining session history.
14+- Align OpenAI OAuth callback binding and redirect host so `localhost`/IPv6 resolution cannot miss the local callback server.
15+- Fix Windows browser launch for `/login` by using a real cross-platform opener or `cmd /c start`.
16+- Parse `/mcp add ... stdio ...` arguments with shell-style quoting so paths and args with spaces work.
1117
1218 ## Features
1319
docs/mini-coder.1.md+1−227
@@ -1,227 +1 @@
1-# MINI-CODER(1)
2-
3-## NAME
4-
5-**mini-coder** — a small, fast CLI coding agent (executable: `mc`)
6-
7-## SYNOPSIS
8-
9-`mc` \[_options_\] \[_prompt_\]
10-
11-## DESCRIPTION
12-
13-Developer-focused CLI coding agent. Prioritizes dev flow — no slow startup, no GUI, no vendor lock-in. Uses 16 ANSI colors to inherit terminal theme. Built on Bun.js.
14-
15-## OPTIONS
16-
17-`-m`, `--model` _id_
18-: Model to use (e.g. `zen/claude-sonnet-4-6`).
19-
20-`-c`, `--continue`
21-: Continue most recent session.
22-
23-`-r`, `--resume` _id_
24-: Resume a specific session.
25-
26-`-l`, `--list`
27-: List recent sessions.
28-
29-`--cwd` _path_
30-: Set working directory.
31-
32-`-h`, `--help`
33-: Display help.
34-
35-_prompt_
36-: Optional one-shot prompt. Runs once then exits.
37-
38-## INTERACTIVE COMMANDS
39-
40-`/model`
41-: List all available models.
42-
43-`/models`
44-: Alias for `/model`.
45-
46-`/model` _id_
47-: Switch model.
48-
49-`/models` _id_
50-: Alias for `/model` _id_.
51-
52-`/model effort` _low|medium|high|xhigh|off_
53-: Set reasoning effort.
54-
55-`/session` \[_id_\]
56-: List sessions or switch to one.
57-
58-`/new`
59-: Start a fresh session.
60-
61-`/undo`
62-: Remove last turn (does NOT revert filesystem).
63-
64-`/reasoning` \[_on|off_\]
65-: Toggle reasoning display.
66-
67-`/verbose` \[_on|off_\]
68-: Toggle output truncation.
69-
70-`/mcp list`
71-: List MCP servers.
72-
73-`/mcp add` _name_ `http` _url_
74-: Add HTTP MCP server.
75-
76-`/mcp add` _name_ `stdio` _cmd_ \[_args..._\]
77-: Add stdio MCP server.
78-
79-`/mcp remove` _name_
80-: Remove MCP server.
81-
82-`/login`
83-: Show OAuth login status.
84-
85-`/login` _provider_
86-: Login via OAuth (opens browser for device flow). Currently supports `openai`.
87-
88-`/logout` _provider_
89-: Clear saved OAuth tokens.
90-
91-`/help`
92-: Command help.
93-
94-`/exit`, `/quit`, `/q`
95-: Leave session.
96-
97-## INLINE FEATURES
98-
99-`!` prefix
100-: Runs shell commands inline — output is sent to the LLM as a user message.
101-
102-`@` prefix
103-: Embeds a file into the prompt (Tab to complete file paths).
104-
105-`/` prefix
106-: Reference a skill in the prompt (Tab to complete skill names).
107-
108-## KEYS
109-
110-`ESC`
111-: Interrupt the assistant response — partial output is preserved in history.
112-
113-`Ctrl+C`
114-: Exit forcefully.
115-
116-`Ctrl+D`
117-: Graceful exit (EOF).
118-
119-`↑` / `↓`
120-: Navigate command history.
121-
122-`Ctrl+R`
123-: Search command history.
124-
125-## BUILT-IN TOOLS
126-
127-**shell**
128-: Execute bash commands; repo inspection and `mc-edit` edits happen here.
129-
130-**listSkills**
131-: List discovered skills (metadata only).
132-
133-**readSkill**
134-: Load one SKILL.md on demand.
135-
136-**webSearch**
137-: Search the web (requires `EXA_API_KEY`).
138-
139-**webContent**
140-: Fetch page content (requires `EXA_API_KEY`).
141-
142-MCP tools are connected dynamically from configured MCP servers.
143-
144-## FILE EDITING — mc-edit
145-
146-`mc-edit` is the helper for targeted file edits, invoked from **shell**.
147-
148-```
149-mc-edit <path> (--old <text> | --old-file <path>) [--new <text> | --new-file <path>] [--cwd <path>]
150-```
151-
152-- Applies one exact-text edit to an existing file.
153-- The old text must match exactly once.
154-- Omit `--new`/`--new-file` to delete the matched text.
155-- Success: prints unified diff + metadata (`ok`, `path`, `changed`).
156-- No-op: prints `(no changes)` + metadata.
157-- Errors go to stderr.
158-
159-Workflow: inspect with **shell** → edit with **mc-edit** → verify with **shell**.
160-
161-## SKILLS
162-
163-Skills are reusable instruction files at `.agents/skills/<name>/SKILL.md`.
164-
165-`.claude/skills/<name>/SKILL.md` is also supported.
166-
167-**Frontmatter (both required):**
168-
169-`name`
170-: Lowercase alphanumeric + hyphens, 1–64 chars.
171-
172-`description`
173-: Help text.
174-
175-Skills are auto discovered. To load explicitly:
176-
177-- `/skill-name` in prompts (injects body as a user message).
178-- **listSkills** / **readSkill** tools at runtime.
179-
180-Local discovery walks up from cwd to the git worktree root.
181-
182-## CONFIGURATION
183-
184-Config roots: `.agents/`, `.claude/` — local (repo) or global (`~/`).
185-
186-**Context files** (global files first, then the nearest local directory with context files):
187-
188-- Global files concatenate in this order: `~/.agents/AGENTS.md` → `~/.agents/CLAUDE.md` → `~/.claude/CLAUDE.md`
189-- Local files concatenate in this order within the nearest matching directory (the same nearest-directory precedence applies to both `AGENTS.md` and `CLAUDE.md`): `./.agents/AGENTS.md` → `./.agents/CLAUDE.md` → `./.claude/CLAUDE.md` → `./CLAUDE.md` → `./AGENTS.md`
190-
191-**Precedence:**
192-
193-1. Local context is loaded from the nearest directory between cwd and the git root.
194-2. Within one scope, matching files are concatenated in the order above.
195-3. Global context appears before local context in the system prompt.
196-4. Skills: nearest ancestor directory wins.
197-
198-## ENVIRONMENT
199-
200-`OPENCODE_API_KEY`
201-: OpenCode Zen (recommended).
202-
203-`ANTHROPIC_API_KEY`
204-: Direct Anthropic.
205-
206-`OPENAI_API_KEY`
207-: Direct OpenAI.
208-
209-`GOOGLE_API_KEY` / `GEMINI_API_KEY`
210-: Direct Gemini.
211-
212-`OLLAMA_BASE_URL`
213-: Ollama local (defaults to `http://localhost:11434`).
214-
215-`EXA_API_KEY`
216-: Enables **webSearch** / **webContent**.
217-
218-## FILES
219-
220-`~/.config/mini-coder/`
221-: App data directory (sessions.db, with tables for error and other logs).
222-
223-`.agents/` or `.claude/`
224-: Config directories for skills and context files.
225-
226-`AGENTS.md` / `CLAUDE.md`
227-: Project context files.
1+TODO: Make a markdown based man page here once the mini-coder-spec.md is fully implemented.
docs/superpowers/plans/2026-03-30-anthropic-oauth-removal.md+0−61
@@ -1,61 +0,0 @@
1-# Anthropic OAuth Removal Implementation Plan
2-
3-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4-
5-**Goal:** Remove Claude Code subscription OAuth support without affecting Anthropic API-key access or Zen Claude models.
6-
7-**Architecture:** Delete the Anthropic OAuth provider registration and stop consulting Anthropic OAuth state in discovery/model-info paths. Preserve all direct `ANTHROPIC_API_KEY` behavior and Anthropic-family handling needed by Zen and direct API use.
8-
9-**Tech Stack:** Bun, TypeScript, bun:test, SQLite-backed auth storage, AI SDK providers.
10-
11----
12-
13-### Task 1: Track the work and lock the user-facing contract
14-
15-**Files:**
16-
17-- Modify: `TODO.md`
18-- Reference: `docs/superpowers/specs/2026-03-30-anthropic-oauth-removal-design.md`
19-
20-- [ ] **Step 1: Update TODO.md with active work item**
21-- [ ] **Step 2: Keep TODO.md current as tasks complete**
22-
23-### Task 2: Write failing tests for Anthropic OAuth removal
24-
25-**Files:**
26-
27-- Modify: `src/llm-api/providers-resolve.test.ts`
28-- Modify: `src/llm-api/model-info.test.ts`
29-- Create: `src/session/oauth/auth-storage.test.ts`
30-
31-- [ ] **Step 1: Add a test asserting OAuth providers list only OpenAI**
32-- [ ] **Step 2: Add tests asserting Anthropic discovery requires `ANTHROPIC_API_KEY`**
33-- [ ] **Step 3: Run focused tests to verify they fail for the expected reason**
34-
35-### Task 3: Remove Anthropic OAuth registration and discovery usage
36-
37-**Files:**
38-
39-- Delete: `src/session/oauth/anthropic.ts`
40-- Modify: `src/session/oauth/auth-storage.ts`
41-- Modify: `src/llm-api/providers.ts`
42-- Modify: `src/llm-api/model-info.ts`
43-- Modify: `src/llm-api/model-info-fetch.ts`
44-
45-- [ ] **Step 1: Remove the Anthropic OAuth provider from auth storage**
46-- [ ] **Step 2: Remove Anthropic OAuth-based provider discovery/autodiscovery**
47-- [ ] **Step 3: Remove Anthropic OAuth-based model list fetching**
48-- [ ] **Step 4: Run the focused tests and make them pass**
49-
50-### Task 4: Update CLI/docs and finish verification
51-
52-**Files:**
53-
54-- Modify: `src/cli/commands-help.ts`
55-- Modify: `docs/mini-coder.1.md`
56-- Modify: `TODO.md`
57-
58-- [ ] **Step 1: Remove Anthropic OAuth mentions from help/manpage**
59-- [ ] **Step 2: Run formatting if needed**
60-- [ ] **Step 3: Run focused tests, then broader verification commands**
61-- [ ] **Step 4: Clear the completed TODO item**
docs/superpowers/specs/2026-03-30-anthropic-oauth-removal-design.md+0−47
@@ -1,47 +0,0 @@
1-# Anthropic OAuth Removal Design
2-
3-## Goal
4-
5-Remove Claude Code subscription OAuth support from mini-coder while preserving:
6-
7-- direct Anthropic API key support via `ANTHROPIC_API_KEY`
8-- Anthropic-family models served through Opencode Zen (`zen/claude-*`)
9-
10-## Approved behavior
11-
12-- `anthropic` is removed completely from the user-facing OAuth surface.
13-- `/login anthropic` is no longer supported and behaves like any unknown provider.
14-- `/logout anthropic` is no longer documented or advertised as a supported path.
15-- Existing saved Anthropic OAuth rows in SQLite are ignored; no migration or cleanup is required.
16-- Anthropic remains available through `ANTHROPIC_API_KEY`.
17-- Zen-backed Claude models remain available and unchanged.
18-
19-## Approach
20-
21-Use a narrow OAuth-only removal:
22-
23-1. Remove the Anthropic OAuth provider module and provider registration.
24-2. Stop consulting Anthropic OAuth state during provider discovery and model-info refresh visibility.
25-3. Keep direct Anthropic provider resolution via `ANTHROPIC_API_KEY`.
26-4. Keep Anthropic-family request handling and Zen backend routing unchanged.
27-5. Update tests and docs to match the new OAuth surface.
28-
29-## Files in scope
30-
31-- `src/session/oauth/anthropic.ts` — delete
32-- `src/session/oauth/auth-storage.ts` — unregister Anthropic OAuth
33-- `src/llm-api/providers.ts` — stop treating Anthropic OAuth as connected
34-- `src/llm-api/model-info.ts` — stop treating Anthropic OAuth as a refresh/visibility source
35-- `src/llm-api/model-info-fetch.ts` — stop fetching Anthropic models via OAuth tokens
36-- `src/cli/commands-help.ts` — remove Anthropic OAuth example text
37-- `docs/mini-coder.1.md` — document OpenAI-only OAuth support
38-- tests around provider discovery/model info — update to be deterministic and Anthropic-OAuth-free
39-
40-## Risks and mitigations
41-
42-- Risk: accidentally breaking direct Anthropic API-key support.
43- - Mitigation: keep direct provider resolver and add/update tests that verify `ANTHROPIC_API_KEY` still wins.
44-- Risk: accidentally breaking Zen Claude behavior.
45- - Mitigation: avoid touching Anthropic-family routing/caching code used for Zen.
46-- Risk: stale Anthropic OAuth tokens still affecting behavior.
47- - Mitigation: remove all Anthropic OAuth checks from discovery and model fetching paths.
mini-coder-spec.md+108−0
@@ -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.