xonecas.io
64875
Mc

mini-coder / commit eb6bd79

docs: sync repo docs with spec

xonecas2026-04-12 eb6bd79b4b942ba4959c50a45989687d75d548aa parent 20d8b6d

3 files changed

README.md+33−29
@@ -43,14 +43,14 @@ Two built-in tools, plus a read-only image tool:
4343
4444 - **`shell`** — runs commands in the user's shell. Returns stdout, stderr, and exit code. Large output is truncated to protect model context.
4545 - **`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.
46-- **`readImage`** — reads PNG, JPEG, GIF, and WebP files as model input. Only registered when the active model supports images.
46+- **`readImage`** — reads PNG, JPEG, GIF, and WebP files so vision-capable models can inspect screenshots and other repo images.
4747
4848 Plugins can add more tools, but the core stays intentionally small.
4949
5050 ## Features
5151
5252 - **Multi-provider model support** — Anthropic, OpenAI, Google, Bedrock, Mistral, Groq, xAI, OpenRouter, Ollama, Copilot, and more via pi-ai.
53-- **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.
53+- **Streaming TUI** — a scrolling markdown log, compact tool blocks, an animated divider, multi-line input, and a one-line pill status bar for model, cwd, git state, and session usage.
5454 - **Session persistence** — SQLite-backed sessions with undo, fork, resume, and cumulative usage stats. Sessions are scoped to the working directory.
5555 - **Reasoning and verbosity controls** — toggle thinking visibility and verbose tool rendering on demand. Preferences persist across launches.
5656 - **[AGENTS.md](https://agents.md) support** — project-specific instructions discovered root-to-leaf, with `~/.agents/` for global instructions.
@@ -59,32 +59,34 @@ Plugins can add more tools, but the core stays intentionally small.
5959
6060 ## Commands
6161
62-| Command | Description |
63-| ------------ | ---------------------------------------------------------------------- |
64-| `/model` | Switch models. Persists as the global default. |
65-| `/session` | List and resume sessions scoped to the current working directory. |
66-| `/new` | Start a fresh session and reset cumulative usage counters. |
67-| `/fork` | Copy the conversation into a new session and continue independently. |
68-| `/undo` | Remove the last conversational turn (does not revert file changes). |
69-| `/reasoning` | Toggle thinking visibility. Persisted and restored on launch. |
70-| `/verbose` | Toggle verbose shell rendering plus edit previews/errors in the log. |
71-| `/login` | Interactive OAuth login for supported providers. |
72-| `/logout` | Clear saved OAuth credentials for a logged-in provider. |
73-| `/effort` | Set reasoning effort: low, medium, high, or xhigh. |
74-| `/help` | List commands, loaded AGENTS.md files, discovered skills, and plugins. |
62+| Command | Description |
63+| ------------ | ------------------------------------------------------------------------------------------------------ |
64+| `/model` | Switch models and save the choice as the global default. |
65+| `/session` | Open the session picker for the current working directory. |
66+| `/new` | Start a fresh session and reset the running token and cost totals. |
67+| `/fork` | Fork the current chat into a new session, keep the original, and add a UI-only `Forked session.` note. |
68+| `/undo` | Remove the last conversational turn without touching filesystem changes. |
69+| `/reasoning` | Show or hide model thinking. The setting is saved and restored on launch. |
70+| `/verbose` | Expand shell output plus edit previews and edit errors in the conversation log. |
71+| `/login` | Sign in with a supported OAuth provider. |
72+| `/logout` | Remove saved OAuth credentials for a logged-in provider. |
73+| `/effort` | Choose low, medium, high, or xhigh reasoning effort. |
74+| `/help` | Show commands, current toggles, loaded AGENTS.md files, skills, and plugins. |
7575
7676 ## Key bindings
7777
78-| Key | Action |
79-| ------------- | ------------------------------------------------------------------------------------------------- |
80-| `Enter` | Submit message |
81-| `Shift+Enter` | Insert newline |
82-| `Escape` | Close the current overlay and refocus input; otherwise interrupt the active turn; otherwise no-op |
83-| `Tab` | File path autocomplete (or command filter on `/`) |
84-| `Ctrl+R` | Search global raw input history |
85-| `Ctrl+C` | Graceful exit |
86-| `Ctrl+D` | Graceful exit (EOF, when input is empty) |
87-| `:q` | Graceful exit |
78+| Key | Action |
79+| ------------- | ---------------------------------------------------------------------------------------------------------- |
80+| `Enter` | Submit message |
81+| `Shift+Enter` | Insert newline |
82+| `Escape` | Dismiss the overlay without changing the draft; otherwise interrupt the running turn; otherwise do nothing |
83+| `Tab` | Autocomplete a path, or open the command picker when the draft starts with `/` |
84+| `Ctrl+R` | Search global raw input history |
85+| `Ctrl+C` | Graceful exit |
86+| `Ctrl+D` | Graceful exit when the input is empty |
87+| `:q` | Graceful exit |
88+| `Ctrl+Z` | Suspend the process |
89+| Mouse wheel | Scroll conversation history |
8890
8991 ## Headless one-shot mode
9092
@@ -95,10 +97,12 @@ $ mc -p "summarize this repo"
9597 $ printf '%s\n' 'fix the failing tests' | mc
9698 ```
9799
98-- Enabled when `-p/--prompt` is provided or when stdin/stdout is not a TTY.
99-- Reuses the same input parsing rules as the interactive UI for plain text, `/skill:name`, and standalone image paths.
100-- Streams newline-delimited JSON events to stdout.
101-- Interactive slash commands such as `/model` and `/help` are not available in headless mode.
100+- Starts when `-p/--prompt` is provided or when stdin or stdout is not a TTY.
101+- If stdout is redirected but stdin is still interactive, pass `-p`; headless mode will not fall back to an interactive prompt.
102+- Uses the same parser as the TUI for plain text, `/skill:name`, and standalone image paths.
103+- Writes raw NDJSON events to stdout for text deltas, tool activity, final messages, and `done` / `error` / `aborted` outcomes.
104+- Headless runs still persist like normal sessions and show up in `/session` history for that working directory.
105+- Interactive slash commands such as `/model`, `/session`, and `/help` are not available in headless mode.
102106
103107 ## Docs
104108
TODO.md+16−10
@@ -7,21 +7,27 @@ The spec.md and code are the sources of truth, not this file, don't assume anyth
77
88 ## Open items
99
10-## Low priority (deffered until further notice)
10+- [ ] `shell` results are flattened into one text blob (`src/tools.ts`, `src/ui/conversation.ts`)
11+- [ ] Invalid `settings.json` is fatal instead of falling back to no saved settings (`src/settings.ts`)
12+- [ ] Escape-over-overlay behavior is not encoded in app code (`src/ui/commands.ts`, `src/ui.ts`)
13+- [ ] Custom provider discovery ignores configured `apiKey` (`src/index.ts`)
1114
12-- [ ] **Many `mc` instances on the same host can cause SQL Busy errors** - Doesn't happen often but I've seen it happen with many mc instances open, which makes sense. We should investigate what we can do to add robustness at the SQL layer.
13-- [ ] **Prevent `/session` from switching sessions mid-run** (`ui/commands.ts`, `ui/agent.ts`) — selecting a session while a turn is active can desync UI state from the session the loop is still writing to.
14-- [ ] **Replace custom XML parsing and frontmatter parsing with dedicated dependencies** (`skills.ts`, `prompt.ts`)
15+## Low priority (deferred until further notice)
1516
16-## Plugin related (documented only, no plugin related work is planned right now)
17+- [ ] Slash-command autocomplete does not preserve the draft (`src/ui/commands.ts`)
18+- [ ] Many `mc` instances on the same host can cause SQL Busy errors
19+- [ ] `/session` can switch sessions mid-run (`ui/commands.ts`, `ui/agent.ts`)
20+- [ ] Custom XML parsing and frontmatter parsing are still in use (`skills.ts`, `prompt.ts`)
1721
18-- [ ] **Reconcile the plugin tool execution API with the spec/docs** (`plugins.ts`, `index.ts`, `spec.md`) — the implementation currently needs an undocumented `toolHandlers` map in addition to `tools`, so spec-shaped plugin tools can be advertised to the model but still fail at runtime.
19-- [ ] **Current plugin `AgentContext.messages` is stale** (`index.ts`) — plugin context currently gets a startup snapshot instead of the live current session messages.
20-- [ ] **Package-name and config-relative plugin imports do not work** (`plugins.ts`) — plugin config says `module` can be a package name or path, but current loading always resolves as a filesystem path from the process CWD.
21-- [ ] **Prefix plugin tool rendering with `plugin/tool` in the log** (`index.ts`, `ui/conversation.ts`) — generic plugin tool blocks currently show only the bare tool name, so collisions are ambiguous and the UI does not match the spec.
22+## Plugin related (documented only, no plugin-related work is planned right now)
23+
24+- [ ] Plugin tool execution API does not match the spec/docs (`plugins.ts`, `index.ts`, `spec.md`)
25+- [ ] Plugin `AgentContext.messages` is stale (`index.ts`)
26+- [ ] Package-name and config-relative plugin imports do not work (`plugins.ts`)
27+- [ ] Plugin tool rendering is not prefixed with `plugin/tool` in the log (`index.ts`, `ui/conversation.ts`)
2228
2329 ## Future ideas
2430
25-- [ ] cel-tui now supports setting the terminal title text. We should use this to show activity and session information to the user: "Preview of last assistant/user message... - <animation if turn is in flight in sync with divider animation>". Use a simple animation, like a repeating elipsis. we just need to make sure that if the divider is on, the window title is too, they can't be out of sync, that would be confusing.
31+- [ ] Terminal title should show activity/session info and stay in sync with the divider animation
2632 - [ ] Divider theme plugin — customizable divider animations (scanning pulse, breathing, flowing dots, wave)
2733 - [ ] Backward-compatibility and migration policy for 1.0 (session/app data versioning, explicit migration strategy)
spec.md+17−16
@@ -517,7 +517,7 @@ One line, two-sided, rendered as compact padded pills rather than a full-width f
517517
518518 **Right side:**
519519
520-- Inner-right: git branch, working tree counts (+ staged, ~ modified, ? untracked), ahead of remote (▲ N). Omitted outside a repo.
520+- Inner-right: git branch, working tree counts (+ staged, ~ modified, ? untracked), and remote divergence counts when present (▲ N ahead, ▼ N behind). Omitted outside a repo.
521521 - Outer-right: `in:input out:output · context%/window · $cost`. `in`, `out`, and `$cost` are **cumulative for the session**. `context%/window` shows the **estimated current context usage for the next model request** as a percentage of the active model's context window.
522522 - Context tone mapping: `<25%` → scale 0, `25-49.9%` → scale 1, `50-74.9%` → scale 2, `75-89.9%` → scale 3, `>=90%` → scale 4.
523523
@@ -528,7 +528,7 @@ Token counts use human-friendly units (1.2k, 45k, 1.2M). Context usage is estima
528528 ```text
529529 [ anthropic/sonnet-4 · med ] [ ~/src/mini-coder ] [ main +3 ~1 ▲ 2 ] [ in:1.2k out:0.8k · 42.0%/200k · $0.03 ]
530530 [ openai/gpt-5-mini · low ] [ ~/src/mini-coder ] [ in:220 out:90 · 8.0%/200k · $0.00 ]
531-[ openrouter/qwen3-coder · xhigh ] [ …/mini-coder ] [ feat/ui ~4 ?2 ▲ 7 ] [ in:180k out:24k · 93.0%/200k · $2.10 ]
531+[ openrouter/qwen3-coder · xhigh ] [ …/mini-coder ] [ feat/ui ~4 ?2 ▲ 7 ▼ 1 ] [ in:180k out:24k · 93.0%/200k · $2.10 ]
532532 ```
533533
534534 The outer-left pill tone changes with effort, the outer-right pill tone changes with context pressure, and the inner pills stay neutral.
@@ -544,10 +544,10 @@ Tool blocks share a common frame: a left border (`│`) plus a compact header pi
544544 - **User messages**: displayed as plain text with a subtle background color to distinguish them from agent responses. No prefix or role indicator.
545545 - **Assistant messages**: streamed raw markdown rendered via cel-tui's `SyntaxHighlight` component on the default background so the log stays copy-friendly and preserves markdown markers. Thinking/reasoning content is collapsible (shown or hidden according to the user's persisted `/reasoning` preference; defaults to shown when no setting exists).
546546 - **Tool calls — shell**: rendered in the shared tool frame. The assistant tool call streams the command as it arrives. The command preview and shell tool result body use [verbose tool rendering](#verbose-tool-rendering). Shell tool results render the tool output content below a `shell <-` header.
547-- **Tool calls — edit**: rendered in the shared tool frame. The in-progress tool-call preview shows the target path plus the streamed replacement content, preserving whitespace. The preview body uses [verbose tool rendering](#verbose-tool-rendering). Successful results render a compact confirmation block (`edit <-` plus the file path); errors render the returned error text.
547+- **Tool calls — edit**: rendered in the shared tool frame. The in-progress tool-call preview shows the target path followed by the streamed `oldText` and `newText` bodies. Old text is styled as removed and new text as added, but the preview does not render literal `-`/`+` diff prefixes. The preview body uses [verbose tool rendering](#verbose-tool-rendering). Successful results render a compact confirmation block (`edit <-` plus the file path); errors render the returned error text.
548548 - **Tool calls — readImage**: rendered in the shared tool frame. The assistant tool call streams the path as it arrives. Successful results render a compact result block (`read image <-` plus the file path) rather than rendering the image itself.
549549 - **Tool calls — plugin tools**: rendered in the shared tool frame, prefixed with plugin/tool name when available.
550-- **UI messages**: internal app messages such as `/help` output, OAuth progress, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering.
550+- **UI messages**: internal app messages such as `/help` output, OAuth progress, `/fork` notices, and other session-local notices. They are rendered in the conversation log, persisted with the session, excluded from model context, and do not participate in conversational turn numbering.
551551 - **Errors**: one-line summary, styled distinctly.
552552
553553 #### Verbose tool rendering
@@ -631,7 +631,7 @@ Representative entry shapes:
631631 │ edit ->
632632 │ src/session.ts
633633 │ const turn = getCurrentTurn(sessionId);
634- │ saveMessage(sessionId, turn, message);
634+ │ const turn = getNextTurn(sessionId);
635635 │ And 9 lines more
636636 ```
637637
@@ -640,6 +640,7 @@ Representative entry shapes:
640640 ```text
641641 │ edit ->
642642 │ src/session.ts
643+ │ const turn = getCurrentTurn(sessionId);
643644 │ const turn = getNextTurn(sessionId);
644645 │ saveMessage(sessionId, turn, message);
645646 │ return turn;
@@ -742,7 +743,7 @@ add tests for undo_
742743 | `/model` | Interactive model selector. The list includes built-in models plus any custom OpenAI-compatible models discovered from `settings.json`. Switching models mid-session is allowed — pi-ai's context is model-agnostic. The `readImage` tool is re-evaluated (added/removed based on the new model's capabilities). The status bar updates immediately, and the selected model is persisted immediately as the user's global default. The session record's `model` field is not updated (it reflects …
743744 | `/session` | Interactive session manager (list, resume). Sessions scoped to CWD. …
744745 | `/new` | Start a new session. Clears conversation, resets cost/token counters. …
745-| `/fork` | Fork the current conversation into a new session. Copies the full message history, continues from here independently. The original session is preserved. …
746+| `/fork` | Fork the current conversation into a new session. Copies the full message history, continues from here independently, and appends a UI-only `Forked session.` notice in the new session. The original session is preserved. …
746747 | `/undo` | Remove the last conversational turn from history: the most recent user message and all assistant/tool messages that followed in that turn. Persisted UI messages are not part of turns and are not removed by `/undo`. Context-only — does not revert filesystem changes. …
747748 | `/reasoning` | Toggle display of model thinking/reasoning content in the log. The new on/off state is persisted immediately and restored on launch. When no setting exists yet, reasoning defaults to shown. …
748749 | `/verbose` | Toggle [verbose tool rendering](#verbose-tool-rendering) for shell previews/results, edit previews, and edit errors. Successful edit results stay compact regardless of this setting. …
@@ -909,7 +910,7 @@ CREATE INDEX idx_prompt_history_created_at ON prompt_history(created_at, id);
909910
910911 **Messages as JSON blobs**: pi-ai's `Message` type (UserMessage, AssistantMessage, ToolResultMessage) is already serializable, and we also persist internal UI-only log entries in the same table. We store the full object as JSON in `data` rather than normalizing into columns. Session load returns the complete chronological log; model context construction filters out UI-only messages before replaying the remaining pi-ai messages into a pi-ai `Context`.
911912
912-**Turn grouping**: the `turn` column groups only conversational messages. A turn is: one user message + one or more assistant messages + any tool result messages from that agent loop. Persisted UI messages are stored alongside them but have `turn = NULL`, so they remain visible in session history without becoming part of `/undo`. `/fork` copies all persisted messages to a new session, preserving conversational turn numbers and UI messages as-is.
913+**Turn grouping**: the `turn` column groups only conversational messages. A turn is: one user message + one or more assistant messages + any tool result messages from that agent loop. Persisted UI messages are stored alongside them but have `turn = NULL`, so they remain visible in session history without becoming part of `/undo`. `/fork` copies all existing persisted messages to a new session, preserving conversational turn numbers and existing UI messages as-is, then appends a new UI-only notic …
913914
914915 **Cumulative stats are computed, not stored**: the status bar's cumulative `in`, `out`, and `$cost` values are computed by summing `usage` from assistant messages on session load (deserialize all messages, filter for `role: "assistant"`, sum their `usage` fields). The message count per session is small (hundreds), so this is fast. No separate counters to keep in sync. During an active session, a running in-memory accumulator is updated after each assistant message to avoid re-scanning. `context% …
915916
@@ -923,12 +924,12 @@ CREATE INDEX idx_prompt_history_created_at ON prompt_history(created_at, id);
923924
924925 ### Operations
925926
926-| Operation | SQL |
927-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
928-| New session | `INSERT INTO sessions` |
929-| Append message | `INSERT INTO messages` with the current conversational turn number (or `NULL` for UI-only messages), `UPDATE sessions SET updated_at` |
930-| Undo | `DELETE FROM messages WHERE session_id = ? AND turn = (SELECT MAX(turn) FROM messages WHERE session_id = ?)` |
931-| Fork | `INSERT INTO sessions` (new id, `forked_from` set), then `INSERT INTO messages SELECT ... FROM messages WHERE session_id = ?` (copy all, new session_id) |
932-| List sessions | `SELECT * FROM sessions WHERE cwd = ? ORDER BY updated_at DESC` |
933-| Load session | `SELECT data FROM messages WHERE session_id = ? ORDER BY id` → parse JSON → persisted message log (`pi-ai Message[]` + internal UI messages) |
934-| Delete session | `DELETE FROM sessions WHERE id = ?` (cascade deletes messages) |
927+| Operation | SQL |
928+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
929+| New session | `INSERT INTO sessions` |
930+| Append message | `INSERT INTO messages` with the current conversational turn number (or `NULL` for UI-only messages), `UPDATE sessions SET updated_at` |
931+| Undo | `DELETE FROM messages WHERE session_id = ? AND turn = (SELECT MAX(turn) FROM messages WHERE session_id = ?)` |
932+| Fork | `INSERT INTO sessions` (new id, `forked_from` set), then `INSERT INTO messages SELECT ... FROM messages WHERE session_id = ?` (copy all, new session_id), then append a UI-only fork notice with `turn = NULL` |
933+| List sessions | `SELECT * FROM sessions WHERE cwd = ? ORDER BY updated_at DESC` |
934+| Load session | `SELECT data FROM messages WHERE session_id = ? ORDER BY id` → parse JSON → persisted message log (`pi-ai Message[]` + internal UI messages) |
935+| Delete session | `DELETE FROM sessions WHERE id = ?` (cascade deletes messages) |