mini-coder 0.4.1 → 0.5.1

package/README.md

@@ -1,80 +1,121 @@
 <p align="center">
-  <img src="assets/icon-5-community-badge.svg" alt="mini-coder logo" width="100" height="100"/>
+  <img src="assets/icon-2-dark-terminal.svg" alt="mini-coder logo" width="112" />
 </p>
 
-# 👾 mini-coder
+<h1 align="center">mini-coder</h1>
 
-> _Small. Fast. Gets out of your way._
-
-[📖 Read the Full Manual](docs/mini-coder.1.md)
-
-A terminal coding agent for developers who want a sharp tool, not a bloated IDE plugin. Shell-first, multi-provider, minimal tool surface. Just you, your terminal, and an AI that keeps up.
+<p align="center"><strong>Lightning-fast coding agent for your terminal.</strong></p>
 
 <p align="center">
-  <img src="./assets/preview.gif" alt="Minicoder Preview"/>
+  <a href="https://www.npmjs.com/package/mini-coder">npm</a>
+  ·
+  <a href="https://sacenox.github.io/mini-coder/">docs</a>
+  ·
+  <a href="spec.md">spec</a>
 </p>
 
----
+<p align="center">
+  <picture>
+    <img src="assets/preview.gif" alt="mini-coder terminal session preview" width="960" style="border-radius: 10px; box-shadow: 0 10px 30px rgba(0,0,0,0.35);" />
+  </picture>
+</p>
 
-## ⚡ Quick Start
+mini-coder (`mc`) is a terminal coding agent that reads your repo, edits files, runs commands, and keeps going until the work is done. Small core tool surface, flat architecture, fast turns, and streaming everywhere it matters.
 
-I run on [Bun](https://bun.com) — install me via bun or npm, but Bun needs to be on your machine.
+## Install
 
 ```bash
-# Install
-bun add -g mini-coder   # or: npm install -g mini-coder
+$ bun add -g mini-coder
+$ mc
+```
 
-# Set one API key (pick any)
-export OPENCODE_API_KEY=your-key     # recommended
-export ANTHROPIC_API_KEY=your-key    # direct Anthropic
-export OPENAI_API_KEY=your-key       # direct OpenAI
-export GOOGLE_API_KEY=your-key       # direct Gemini (or GEMINI_API_KEY)
+## Why mini-coder?
 
-# Optional
-export OLLAMA_BASE_URL=http://localhost:11434   # local models
-export EXA_API_KEY=your-key                     # web search tools
+- **Lean on proven dependencies** — [pi-ai](https://github.com/badlogic/pi-mono/tree/main/packages/ai) for providers, streaming, tool calling, usage tracking, and OAuth. [cel-tui](https://github.com/sacenox/cel-tui) for the terminal UI. The core stays focused on agent work.
+- **Flat, simple codebase** — no workspaces, no internal abstraction layers. Files grouped by concern in a single `src/` directory.
+- **Agent-first** — every decision serves the goal of reading code, making changes, and verifying them via the shell.
+- **Performance** — startup and turn latency matter more than features.
+- **Streaming end-to-end** — assistant text, reasoning, tool calls, and tool output show up as they happen.
 
-# Go
-mc
-```
+## Tools
 
-One-shot mode: `mc "refactor auth to use async/await"` — runs once, then exits.
+Two built-in tools, plus a read-only image tool:
 
-Useful flags: `-c` continue last session, `-r <id>` resume, `-l` list sessions, `-m <model>` pick a model, `-h` help.
+- **`shell`** — runs commands in the user's shell. Returns stdout, stderr, and exit code. Large output is truncated to protect model context.
+- **`edit`** — exact-text replacement in a single file. Fails deterministically if the target is missing or ambiguous. Creates new files when old text is empty.
+- **`readImage`** — reads PNG, JPEG, GIF, and WebP files as model input. Only registered when the active model supports images.
 
----
+Plugins can add more tools, but the core stays intentionally small.
 
-## 🔑 OAuth Login
+## Features
 
-Use `/login` inside the REPL to authenticate via browser-based OAuth. Currently supported: `openai` (`/login openai` uses the Codex / ChatGPT Plus/Pro flow). No need to manage API keys manually.
+- **Multi-provider model support** — Anthropic, OpenAI, Google, Bedrock, Mistral, Groq, xAI, OpenRouter, Ollama, Copilot, and more via pi-ai.
+- **Streaming TUI** — markdown conversation log, tool blocks with diffs, animated divider, multi-line input, and a one-line pill status bar with independent ANSI16 effort/context tones.
+- **Session persistence** — SQLite-backed sessions with undo, fork, resume, and cumulative usage stats. Sessions are scoped to the working directory.
+- **Reasoning and verbosity controls** — toggle thinking visibility and verbose tool rendering on demand. Preferences persist across launches.
+- **[AGENTS.md](https://agents.md) support** — project-specific instructions discovered root-to-leaf, with `~/.agents/` for global instructions.
+- **[Agent Skills](https://agentskills.io)** — skill catalogs exposed in the prompt. `/skill:name` injects a skill body into the next user message.
+- **Plugins** — optional tools, integrations, theme overrides, and prompt suffixes without bloating the core.
 
----
+## Commands
 
-## 🛠️ Features
+| Command      | Description                                                            |
+| ------------ | ---------------------------------------------------------------------- |
+| `/model`     | Switch models. Persists as the global default.                         |
+| `/session`   | List and resume sessions scoped to the current working directory.      |
+| `/new`       | Start a fresh session and reset cumulative usage counters.             |
+| `/fork`      | Copy the conversation into a new session and continue independently.   |
+| `/undo`      | Remove the last conversational turn (does not revert file changes).    |
+| `/reasoning` | Toggle thinking visibility. Persisted and restored on launch.          |
+| `/verbose`   | Toggle verbose shell rendering plus edit previews/errors in the log.   |
+| `/login`     | Interactive OAuth login for supported providers.                       |
+| `/logout`    | Clear saved OAuth credentials for a logged-in provider.                |
+| `/effort`    | Set reasoning effort: low, medium, high, or xhigh.                     |
+| `/help`      | List commands, loaded AGENTS.md files, discovered skills, and plugins. |
 
-- **Multi-provider** — supports Anthropic, OpenAI (direct + OAuth), Gemini, and Ollama
-- **Session memory** — SQLite-backed. Resume with `-c` or `-r <id>`
-- **Shell integration** — `!` prefix for inline commands, `@` to reference files with tab completion
-- **Web search** — `webSearch` + `webContent` tools when `EXA_API_KEY` is set
-- **MCP support** — connect external tool servers over HTTP or stdio
-- **Skills** — `.agents/skills/<name>/SKILL.md`, invoke with `/skill-name` in the prompt
-- **`mc-edit`** — safe, exact-text file editing (no full-file rewrites)
-- **16 ANSI colors** — inherits your terminal theme. Always looks right.
+## Key bindings
 
----
+| Key           | Action                                            |
+| ------------- | ------------------------------------------------- |
+| `Enter`       | Submit message                                    |
+| `Shift+Enter` | Insert newline                                    |
+| `Escape`      | Interrupt current turn, preserve partial response |
+| `Tab`         | File path autocomplete (or command filter on `/`) |
+| `Ctrl+R`      | Search global raw input history                   |
+| `Ctrl+C`      | Graceful exit                                     |
+| `Ctrl+D`      | Graceful exit (EOF, when input is empty)          |
+| `:q`          | Graceful exit                                     |
 
-## 📚 Getting Deeper
+## Headless one-shot mode
 
-The README is the highlight reel. For the full story — slash commands, config folders, context files, app data, and everything else:
+mini-coder also supports a non-interactive one-shot mode for scripts and benchmark harnesses.
 
-**[📖 Read the Full Manual](docs/mini-coder.1.md)**
+```bash
+$ mc -p "summarize this repo"
+$ printf '%s\n' 'fix the failing tests' | mc
+```
+
+- Enabled when `-p/--prompt` is provided or when stdin/stdout is not a TTY.
+- Reuses the same input parsing rules as the interactive UI for plain text, `/skill:name`, and standalone image paths.
+- Streams newline-delimited JSON events to stdout.
+- Interactive slash commands such as `/model` and `/help` are not available in headless mode.
 
----
+## Docs
 
-## 🔮 Tech Stack
+- **Docs site:** https://sacenox.github.io/mini-coder/
+- **Spec:** [`spec.md`](spec.md)
+- **Repo instructions:** [`AGENTS.md`](AGENTS.md)
 
-[Bun.js](https://bun.com) · [AI SDK](https://ai-sdk.dev) · [yoctocolors](https://github.com/sindresorhus/yoctocolors)
+## Development
+
+```bash
+bun install
+bun test
+bun run check
+bun run format
+bun run typecheck
+```
 
-## 📄 License
+## License
 
-MIT — [github.com/sacenox/mini-coder](https://github.com/sacenox/mini-coder)
+MIT

package/assets/icon-1-minimal.svg

@@ -0,0 +1,31 @@
+<!-- Mini Coder Icon v1: Minimal / Clean
+     Thin brackets, sharp lightning bolt. No fills — pure outline.
+     Inspired by: "small and fast, doesn't get in the way" -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <!-- Left bracket { -->
+  <path
+    d="M38 12 C28 12 24 17 24 25 L24 40 C24 46 20 48 16 50 C20 52 24 54 24 60 L24 75 C24 83 28 88 38 88"
+    fill="none"
+    stroke="#1a1a2e"
+    stroke-width="5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <!-- Right bracket } -->
+  <path
+    d="M62 12 C72 12 76 17 76 25 L76 40 C76 46 80 48 84 50 C80 52 76 54 76 60 L76 75 C76 83 72 88 62 88"
+    fill="none"
+    stroke="#1a1a2e"
+    stroke-width="5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <!-- Lightning bolt -->
+  <path
+    d="M56 22 L43 52 L52 52 L44 78 L62 44 L52 44 Z"
+    fill="#f5c518"
+    stroke="#1a1a2e"
+    stroke-width="1.5"
+    stroke-linejoin="round"
+  />
+</svg>

package/assets/icon-2-dark-terminal.svg

@@ -0,0 +1,48 @@
+<!-- Mini Coder Icon v2: Dark Terminal
+     Dark background, neon bolt and glowing brackets.
+     Inspired by: terminal aesthetic, ANSI colors, claude code dark UI -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <defs>
+    <radialGradient id="bgGlow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#0d1117"/>
+      <stop offset="100%" stop-color="#010409"/>
+    </radialGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="2.5" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background rounded square -->
+  <rect x="4" y="4" width="92" height="92" rx="18" fill="url(#bgGlow)"/>
+
+  <!-- Left bracket { — neon cyan -->
+  <path
+    d="M38 14 C29 14 26 19 26 27 L26 41 C26 47 22 49 18 51 C22 53 26 55 26 61 L26 74 C26 82 29 87 38 87"
+    fill="none"
+    stroke="#00d4ff"
+    stroke-width="4.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    filter="url(#glow)"
+  />
+  <!-- Right bracket } — neon cyan -->
+  <path
+    d="M62 14 C71 14 74 19 74 27 L74 41 C74 47 78 49 82 51 C78 53 74 55 74 61 L74 74 C74 82 71 87 62 87"
+    fill="none"
+    stroke="#00d4ff"
+    stroke-width="4.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    filter="url(#glow)"
+  />
+  <!-- Lightning bolt — electric yellow -->
+  <path
+    d="M57 20 L42 53 L52 53 L43 80 L63 45 L53 45 Z"
+    fill="#ffe600"
+    filter="url(#glow)"
+  />
+</svg>

package/assets/icon-3-gradient-modern.svg

@@ -0,0 +1,45 @@
+<!-- Mini Coder Icon v3: Gradient Modern
+     Purple-to-blue gradient background, white brackets, gradient bolt.
+     Inspired by: "fast and performant", speed gradient feeling -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <defs>
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#6c3de8"/>
+      <stop offset="100%" stop-color="#1a73e8"/>
+    </linearGradient>
+    <linearGradient id="boltGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#fff176"/>
+      <stop offset="100%" stop-color="#ff8c00"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background pill/squircle -->
+  <rect x="2" y="2" width="96" height="96" rx="22" fill="url(#bgGrad)"/>
+
+  <!-- Left bracket { — white -->
+  <path
+    d="M37 13 C27 13 24 18 24 26 L24 41 C24 47 20 49 16 51 C20 53 24 55 24 61 L24 75 C24 83 27 88 37 88"
+    fill="none"
+    stroke="rgba(255,255,255,0.92)"
+    stroke-width="5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <!-- Right bracket } — white -->
+  <path
+    d="M63 13 C73 13 76 18 76 26 L76 41 C76 47 80 49 84 51 C80 53 76 55 76 61 L76 75 C76 83 73 88 63 88"
+    fill="none"
+    stroke="rgba(255,255,255,0.92)"
+    stroke-width="5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <!-- Lightning bolt — warm gradient -->
+  <path
+    d="M57 19 L42 52 L52 52 L44 81 L63 45 L52 45 Z"
+    fill="url(#boltGrad)"
+    stroke="rgba(255,255,255,0.3)"
+    stroke-width="1"
+    stroke-linejoin="round"
+  />
+</svg>

package/assets/icon-4-filled-bold.svg

@@ -0,0 +1,54 @@
+<!-- Mini Coder Icon v4: Filled Bold
+     Chunky solid brackets form a unified shape. Bolt cuts through like a slash.
+     Inspired by: "accurate and reliable", sturdy and trustworthy feel -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <!-- Left bracket { — filled, bold, warm off-white bg -->
+  <rect x="0" y="0" width="100" height="100" rx="0" fill="#f7f3ee"/>
+
+  <!-- Left brace as thick filled path -->
+  <path
+    d="M40 10
+       C32 10 28 15 28 23
+       L28 39
+       C28 45 24 48 19 50
+       C24 52 28 55 28 61
+       L28 77
+       C28 85 32 90 40 90
+       L40 83
+       C35 83 35 79 35 75
+       L35 62
+       C35 55 31 52 28 50
+       C31 48 35 45 35 38
+       L35 25
+       C35 21 35 17 40 17
+       Z"
+    fill="#1a1a2e"
+  />
+  <!-- Right brace as thick filled path -->
+  <path
+    d="M60 10
+       C68 10 72 15 72 23
+       L72 39
+       C72 45 76 48 81 50
+       C76 52 72 55 72 61
+       L72 77
+       C72 85 68 90 60 90
+       L60 83
+       C65 83 65 79 65 75
+       L65 62
+       C65 55 69 52 72 50
+       C69 48 65 45 65 38
+       L65 25
+       C65 21 65 17 60 17
+       Z"
+    fill="#1a1a2e"
+  />
+  <!-- Lightning bolt — punchy orange-red -->
+  <path
+    d="M58 16 L41 51 L52 51 L42 84 L64 47 L53 47 Z"
+    fill="#e8390e"
+    stroke="#f7f3ee"
+    stroke-width="1.5"
+    stroke-linejoin="round"
+  />
+</svg>

package/assets/icon-5-community-badge.svg

@@ -0,0 +1,63 @@
+<!-- Mini Coder Icon v5: Community Badge
+     Hexagonal badge shape (nod to community/open-source), teal + amber palette.
+     Bolt doubles as a "play / run" symbol. Inspired by: "community oriented",
+     open source tools like Codex & opencode. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <defs>
+    <linearGradient id="hexGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0a3d62"/>
+      <stop offset="100%" stop-color="#0c6e6e"/>
+    </linearGradient>
+    <filter id="shadow" x="-10%" y="-10%" width="120%" height="120%">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="rgba(0,0,0,0.35)"/>
+    </filter>
+  </defs>
+
+  <!-- Hexagon background -->
+  <polygon
+    points="50,4 93,27 93,73 50,96 7,73 7,27"
+    fill="url(#hexGrad)"
+    filter="url(#shadow)"
+  />
+  <!-- Subtle inner hex ring -->
+  <polygon
+    points="50,10 88,30 88,70 50,90 12,70 12,30"
+    fill="none"
+    stroke="rgba(255,255,255,0.1)"
+    stroke-width="1.5"
+  />
+
+  <!-- Left bracket { — teal/white -->
+  <path
+    d="M37 18 C29 18 26 23 26 30 L26 43 C26 48 22 51 18 52 C22 53 26 56 26 61 L26 71 C26 78 29 83 37 83"
+    fill="none"
+    stroke="#7fffd4"
+    stroke-width="4"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <!-- Right bracket } — teal/white -->
+  <path
+    d="M63 18 C71 18 74 23 74 30 L74 43 C74 48 78 51 82 52 C78 53 74 56 74 61 L74 71 C74 78 71 83 63 83"
+    fill="none"
+    stroke="#7fffd4"
+    stroke-width="4"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+
+  <!-- Lightning bolt — amber gold -->
+  <path
+    d="M56 22 L42 52 L52 52 L44 78 L62 46 L51 46 Z"
+    fill="#ffc107"
+    stroke="#fff8e1"
+    stroke-width="1"
+    stroke-linejoin="round"
+  />
+  <!-- Tiny speed lines left of bolt -->
+  <line x1="28" y1="46" x2="36" y2="46" stroke="#7fffd4" stroke-width="1.5" stroke-linecap="round" opacity="0.5"/>
+  <line x1="30" y1="51" x2="36" y2="51" stroke="#7fffd4" stroke-width="1.5" stroke-linecap="round" opacity="0.35"/>
+  <!-- Tiny speed lines right of bolt -->
+  <line x1="64" y1="46" x2="72" y2="46" stroke="#7fffd4" stroke-width="1.5" stroke-linecap="round" opacity="0.5"/>
+  <line x1="64" y1="51" x2="70" y2="51" stroke="#7fffd4" stroke-width="1.5" stroke-linecap="round" opacity="0.35"/>
+</svg>

package/bin/mc.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+
+/**
+ * Executable launcher for the mini-coder CLI.
+ *
+ * @module
+ */
+
+import { main } from "../src/index.ts";
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});