@@ -1,200 +0,0 @@
1-# mini-coder — Implementation Plan
2-
3-A small, fast CLI coding agent built with Bun.js. Focused on developer flow,
4-elegant output, and a reliable core feature set.
5-
6----
7-
8-## Setup
9-
10-- Runtime: Bun.js
11-- Language: TypeScript (strict mode)
12-- Binary: `mc` (globally installable via `bun install -g .`)
13-- Config + sessions: `~/.config/mini-coder/`
14-
15----
16-
17-## Dependencies
18-
19-```
20-ai # AI SDK v6 core
21-@ai-sdk/anthropic # Claude via Zen or direct
22-@ai-sdk/openai # GPT via Zen or direct
23-@ai-sdk/google # Gemini via Zen or direct
24-@ai-sdk/openai-compatible # MiniMax, GLM, Kimi via Zen
25-ollama-ai-provider # Local Ollama
26-yoctocolors # ANSI colors (16-color safe, inherits terminal theme)
27-zod # Tool input schemas
28-```
29-
30----
31-
32-## Provider Strategy
33-
34-Uses the correct AI SDK package per endpoint type, following the OpenCode Zen docs:
35-
36-| Provider | Package | Endpoint / Notes |
37-| ------------------------------- | -------------------------- | --------------------------------------------- |
38-| OpenCode Zen — Anthropic models | `@ai-sdk/anthropic` | `https://opencode.ai/zen/v1/messages` |
39-| OpenCode Zen — OpenAI models | `@ai-sdk/openai` | `https://opencode.ai/zen/v1/responses` |
40-| OpenCode Zen — Google models | `@ai-sdk/google` | `https://opencode.ai/zen/v1/models/<model>` |
41-| OpenCode Zen — OpenAI-compat | `@ai-sdk/openai-compatible`| `https://opencode.ai/zen/v1/chat/completions` |
42-| Ollama (local) | `ollama-ai-provider` | `http://localhost:11434` (auto-discovered) |
43-
44-### ENV Auto-discovery
45-
46-| ENV var | Effect |
47-| ------------------ | ----------------------------------------- |
48-| `OPENCODE_API_KEY` | Enables OpenCode Zen provider |
49-| `OLLAMA_BASE_URL` | Override Ollama URL (default: localhost) |
50-
51----
52-
53-## Module Architecture
54-
55-```
56-src/
57- index.ts # Entry point — CLI args, wires agent + session
58- cli/
59- input.ts # Raw-mode stdin reader
60- # - Line editing (left/right/backspace/ctrl-keys)
61- # - History (up/down arrows, SQLite-backed)
62- # - @ prefix → file reference autocomplete
63- # - ! prefix → shell passthrough
64- output.ts # ANSI rendering
65- # - Streaming text with cursor animation
66- # - Tool call display (glob/grep/read → formatted args)
67- # - Edit tool → unified diff output
68- # - Shell tool → command + output block
69- # - Status bar: model/provider/cwd/git branch/tokens
70- commands.ts # Slash command registry + handlers
71- # - /model → pick model from connected providers
72- # - /plan → toggle read-only plan mode
73- # - /mcp → list/add/remove MCP servers
74- # - /review → subagent code review
75- llm-api/
76- providers.ts # Provider factory
77- # - ENV-based auto-discovery
78- # - Returns LanguageModel for a given model ID string
79- # - Supports "zen/claude-sonnet-4-6", "ollama/llama3", etc.
80- turn.ts # Single conversation turn
81- # - streamText with tool loop (maxSteps)
82- # - Yields streaming events: text delta, tool call, tool result
83- # - Returns complete turn: messages + usage stats
84- types.ts # Shared types: Message, Turn, ToolCall, ProviderConfig
85- agent/
86- agent.ts # Main agent REPL loop
87- # - Reads input → calls turn → renders output → repeat
88- # - Manages conversation history in memory + persists to DB
89- # - Handles /plan mode (no tool execution)
90- # - Abort on Ctrl+C mid-turn
91- tools.ts # Tool registry + hook system
92- # - Registers all built-in tools
93- # - Runs post-tool hooks (e.g. auto-format after edit)
94- tools/
95- glob.ts # Glob pattern file discovery
96- grep.ts # Regex content search across files
97- read.ts # File read (with line range support)
98- edit.ts # File edit — exact string replacement (old → new)
99- shell.ts # Shell command execution with streaming stdout/stderr
100- subagent.ts # Spawn a nested mini-coder agent instance
101- mcp/
102- client.ts # MCP server connection (stdio + HTTP transports)
103- manager.ts # Add/remove/list MCP servers, persist to config
104- session/
105- db.ts # bun:sqlite schema + query helpers
106- # - sessions table: id, title, cwd, created_at, updated_at
107- # - messages table: id, session_id, role, content, created_at
108- # - prompt_history table: id, text, created_at
109- manager.ts # new / resume / list session operations
110-```
111-
112----
113-
114-## Build Phases
115-
116-### Phase 1 — Foundation
117-
118-- [ ] `bun init` — project setup, `package.json`, `tsconfig.json`, `.gitignore`
119-- [ ] `session/db.ts` — SQLite schema and CRUD helpers
120-- [ ] `llm-api/types.ts` — shared type definitions
121-- [ ] `llm-api/providers.ts` — ENV-based provider factory
122-- [ ] `llm-api/turn.ts` — streaming turn with tool loop
123-
124-### Phase 2 — Tools
125-
126-- [ ] `tools/glob.ts` — glob file search
127-- [ ] `tools/grep.ts` — regex content search
128-- [ ] `tools/read.ts` — file read
129-- [ ] `tools/edit.ts` — file edit (string replace)
130-- [ ] `tools/shell.ts` — shell execution
131-- [ ] `tools/subagent.ts` — nested agent
132-
133-### Phase 3 — CLI
134-
135-- [ ] `cli/input.ts` — raw-mode line editor with history, `@`, `!`
136-- [ ] `cli/output.ts` — ANSI output, tool rendering, diffs, status bar
137-- [ ] `cli/commands.ts` — slash command handlers
138-
139-### Phase 4 — Agent Loop
140-
141-- [ ] `agent/tools.ts` — tool registry and hook system
142-- [ ] `agent/agent.ts` — main REPL loop
143-- [ ] `session/manager.ts` — session new/resume/list
144-- [ ] `src/index.ts` — entry point, CLI args (--new, --resume, --list)
145-
146-### Phase 5 — MCP
147-
148-- [ ] `mcp/client.ts` — MCP client (stdio + HTTP)
149-- [ ] `mcp/manager.ts` — `/mcp` command integration
150-
151----
152-
153-## UI Design Notes
154-
155-- Use only the 16 ANSI colors — colors inherit from the user's terminal theme
156-- No heavy box-drawing unless it reads well in monospace
157-- Status bar (always visible below input):
158- `[model] [provider] [cwd] [git-branch] [ctx%] [↑tokens ↓tokens]`
159-- Tool call output format:
160- - `glob "**/*.ts"` → compact tree of matched paths
161- - `read src/foo.ts:10-30` → file + line range
162- - `edit src/foo.ts` → unified diff (- old / + new)
163- - `shell git status` → command + scrollable output block
164-- Prompt animation: simple spinner (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) while LLM is running
165-
166----
167-
168-## Configuration Schema
169-
170-`~/.config/mini-coder/config.json`:
171-
172-```json
173-{
174- "defaultModel": "zen/claude-sonnet-4-6",
175- "providers": {
176- "zen": { "apiKey": "..." },
177- "ollama": { "baseUrl": "http://localhost:11434" }
178- },
179- "mcpServers": [
180- { "name": "exa", "transport": "http", "url": "https://..." }
181- ]
182-}
183-```
184-
185----
186-
187-## Out of Scope for v1
188-
189-- LSP integration
190-- Image / screenshot support
191-- Web search tool
192-
193----
194-
195-## Conventions
196-
197-- Agent skill files: `.agents/` in project dir or `~/.config/mini-coder/agents/`
198- (follows skills.sh convention)
199-- Context files: `AGENTS.md` or `CLAUDE.md` in project root (same as oh-my-pi / opencode)
200-- No mocked/offline tests — integration tests only against real providers