mini-coder 0.7.3 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,114 @@
+# mini-coder
+
+A fast, transparent, config-first terminal coding agent for one user at a time.
+
+This file holds intent, direction, and guardrails — not a description of the
+code. The source is the source of truth for behavior. If a fact can be learned
+by reading the code, it does not belong here; keep this file short.
+
+## Intent
+
+- A small, auditable core with no hidden machinery.
+- A minimal system prompt with no injected meta-guidance.
+- Provider work delegated entirely to `pi-ai`.
+- Durable, user-owned, readable session logs.
+- An append-only TUI with a bounded live region and no full-screen buffer.
+- Local models (Ollama / llama.cpp / vLLM) and hosted models treated as equals.
+
+Prior art is reference, not template: `x.x.x-archive` (previous implementation),
+`../awl/` (append-only live-region TUI), `../bough/` (layer boundaries), and
+`../agent-ide/` (session durability, streaming). Extract ideas, do not port code.
+
+## Direction
+
+Deferred, not rejected. Do not build unless explicitly promoted:
+
+- context compaction / summarization / masking;
+- reading or resuming sessions (the JSONL log is write-only today);
+- prompt templates; custom agents / subagents / delegation;
+- an extension or plugin system; a settings TUI; overlay editors;
+- custom OAuth or auth flows (use `pi-ai`'s provider auth);
+- MCP, image generation, multi-agent orchestration;
+- sandboxing, approval prompts, permission policies;
+- tests and CI (standing rule: no tests unless asked);
+- macOS/Windows support and cross-platform abstractions. Target Linux first.
+
+## Guardrails
+
+Hard constraints. Do not cross these without explicit direction:
+
+- **Node.js directly.** No Bun, no Deno, no `Bun.*`, no Bun package scripts.
+- **No TUI library or framework.** Render with direct `process.stdout` ANSI
+  writes and plain strings.
+- **`pi-ai` owns the provider layer.** All model requests, adapters, wire
+  formats, streaming, auth, and usage go through `@earendil-works/pi-ai`. Never
+  re-implement a provider protocol, and keep provider-specific continuation data
+  intact.
+- **Write original code.** Other coding agents are behavioral references only.
+- **No sandbox or permission layer.** Tools run with the user's permissions;
+  isolation is an environment concern (`nono`), not the agent's.
+- **No loop limits.** No max turns, tool calls, token budgets, or agent-imposed
+  timeouts. The user's ability to interrupt is the limit.
+- **Config-first.** Every user-facing behavior that can vary comes from config
+  with a sane default. Global config only — no project-local config, no
+  config-override flags — and never duplicate `pi-ai`'s catalog or env vars.
+- **Minimal context.** The model sees the configured system prompt plus
+  explicitly opted-in resource files — never reminders, hidden blocks, or
+  harness meta-text.
+- **Never invent a parallel model.** Consume `pi-ai`'s `Message` and stream
+  types directly.
+- **The agent never imports the TUI.** Headless and TUI are two projections of
+  the same agent events; the TUI owns no agent or provider semantics.
+
+## Invariants
+
+- Sessions are append-only JSONL, one `pi-ai` message per line, fsynced on
+  write. Never rewrite or delete committed lines. A persistence failure stops
+  the turn.
+- The loop has no compaction, no retries, and no meta-messages between steps.
+  Provider errors surface as-is, never masked or summarized.
+- `edit`, `read`, and `bash` only. Tool arguments are untrusted and validated
+  once at the boundary. `read` returns image blocks only for models that declare
+  image input.
+- Interruption: ESC politely pauses at the next step boundary; Ctrl+C cancels the
+  turn (abort the request, kill the tool's process group, persist the aborted
+  message); Ctrl+D exits on an empty draft. Completed side effects are never
+  undone.
+- Diagnostics are local only. No telemetry, no hidden stalls.
+
+## Driving the TUI with kitty
+
+There is no `tmux` here; drive the TUI through kitty's remote control on a
+private socket, one window per session:
+
+    kitty --detach --listen-on unix:/tmp/mc-<name>.sock \
+      -o allow_remote_control=yes -o remember_window_size=no \
+      -o initial_window_width=100c -o initial_window_height=30c \
+      --title mc-<name> env PS1='\n$ ' bash --norc --noprofile -i
+
+Run every `kitty @ --to unix:/tmp/mc-<name>.sock` call through that socket; the
+window id comes from `ls`, don't assume it. Run the app (`node src/cli.ts`) with
+a scratch cwd so its tool calls write nowhere that matters.
+
+- `send-text` types literal text and never submits — Enter is its own key,
+  `send-key enter`, and it does nothing while a turn is active.
+- `send-key` for named keys: `enter escape ctrl+c ctrl+d shift+enter tab`.
+- `get-text -m id:N --extent=all --ansi` returns the pane with the app's
+  truecolor SGR — assert colors from those escapes, not from pixels;
+  `--extent=screen` is the live screen alone.
+- `screenshot -m id:N out.png` for the visual check; `identify` it and look at
+  it before trusting it.
+
+## Working agreement
+
+- Trace the real data flow before designing; apply guards at the narrowest
+  boundary.
+- Keep the diff small. Do not opportunistically refactor or harden adjacent code.
+- Prefer plain functions and objects; keep exports minimal; define helpers near
+  their use.
+- Validate untrusted input once at the boundary with Typebox, then keep internal
+  code plain-typed.
+- Ask before adding a dependency.
+- Do not add tests unless explicitly asked; verify manually.
+- Before finishing, review the diff against the direction and guardrails, remove
+  anything that added scope, and report any requirement you could not satisfy.

package/README.md

@@ -1,91 +1,78 @@
 <p align="center">
-  <img src="assets/icon-2-dark-terminal.svg" alt="mini-coder logo" width="112" />
+  <img src="demo.gif" alt="mini-coder demo" />
 </p>
 
-<h1 align="center">mini-coder</h1>
+# mini-coder
 
-<p align="center"><strong>Lightning-fast coding agent for your terminal.</strong></p>
-
-<p align="center">
-  <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>
-
-mini-coder (`mc`) is a terminal coding agent, hand crafted for transparency and good engineering performance.
+A fast, transparent, config-first terminal coding agent. One provider request at a time, no
+hidden machinery: `edit`, `read`, and `bash`, an append-only JSONL session log, and a config
+file that decides everything.
 
 ## Install
 
-```bash
-$ bun add -g mini-coder
-$ mc
+```sh
+npm i -g mini-coder
 ```
 
-## Why mini-coder?
+## Configuration
 
-- **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.
-- **Isolation friendly**— works inside [nono](https://nono.sh/). Suggested profile in `nono-mini-coder.json`
+Global config lives at `~/.config/mini-coder/config.json` (`$XDG_CONFIG_HOME/mini-coder/config.json`
+if set). There is no project-local config and no override flags.
 
-## Settings
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-5"
+}
+```
 
-> Warning, settings have changed, update your old settings file!
+Only `provider` and `model` are required. Defaults for the rest:
 
-Global defaults live in `~/.config/mini-coder/settings.json`.
+```json
+{
+  "sessionsDir": "./sessions",
+  "systemPrompt": "",
+  "discoverAgentFiles": true,
+  "skillsDirs": [],
+  "tools": ["edit", "read", "bash"],
+  "thinkingEffort": "medium",
+  "customProviders": []
+}
+```
 
-Create or edit it directly to set the default provider, model, reasoning effort, and any custom models. `customProviders` entries use the pi-ai `Model` shape; the top-level `provider` and `model` select the active entry.
+- `provider` / `model` — any model from the `pi-ai` catalog. Invalid pairs fail with a
+  list of available models for that provider.
+- `sessionsDir` — where append-only session JSONL files are written. (no relative paths for now, absolute paths only).
+- `systemPrompt` — the base of the system prompt. Skills and agent files, if
+  enabled, are appended after it.
+- `discoverAgentFiles` — when true, appends `AGENTS.md` / `CLAUDE.md` found in `~/.agents`
+  and the working directory to the system prompt.
+- `skillsDirs` — directories of skills to advertise (`<dir>/<skill>/SKILL.md` with
+  `name:` and `description:` frontmatter). Paths, not contents, go to the model.
+- `tools` — which of `edit`, `read`, `bash` the agent gets. Tool arguments are untrusted
+  and validated at this boundary regardless.
+- `thinkingEffort` — `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` for models
+  that support reasoning.
+
+### Local and custom models
+
+Hosted and local models are equals. Add unlisted or self-hosted models through
+`customProviders` — the four wire APIs come from `pi-ai`, and auth resolves from your
+environment via `envKeys` (no local model needs it):
 
 ```json
 {
-  "provider": "ollama",
-  "model": "llama3.1:8b",
-  "effort": "medium",
   "customProviders": [
     {
-      "id": "llama3.1:8b",
-      "name": "Llama 3.1 8B (Ollama)",
-      "api": "openai-completions",
-      "provider": "ollama",
+      "id": "ollama",
+      "name": "Ollama",
       "baseUrl": "http://localhost:11434/v1",
-      "reasoning": false,
-      "input": ["text"],
-      "cost": {
-        "input": 0,
-        "output": 0,
-        "cacheRead": 0,
-        "cacheWrite": 0
-      },
-      "contextWindow": 128000,
-      "maxTokens": 32000
+      "api": "openai-completions",
+      "models": ["qwen3-coder:30b", "gpt-oss:20b"]
     }
   ]
 }
 ```
 
-Use `api: "openai-completions"` for OpenAI-compatible servers such as Ollama, vLLM, LiteLLM, and local proxies. For local OpenAI-compatible custom providers, mini-coder supplies the dummy API key required by pi-ai when no real key is needed.
-
-## Also makes LLMs smarter
-
-LLMs famously tell you to walk 50 meters to the car wash — forgetting the car needs to be there too. Not on our watch.
-
-<table align="center">
-  <tr>
-    <td><img src="assets/mc-claude-smart.png" alt="Claude correctly answering the car wash question" width="400" /></td>
-    <td><img src="assets/mc-gpt-smart.png" alt="GPT correctly answering the car wash question" width="400" /></td>
-  </tr>
-</table>
-
-## License
-
-MIT
+`api` is `openai-completions`, `openai-responses`, `anthropic-messages`, or
+`google-generative-ai`. Then point `provider` and `model` at it.

package/bin/mini-coder.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.ts";

package/package.json

@@ -1,30 +1,27 @@
 {
   "name": "mini-coder",
-  "version": "0.7.3",
+  "version": "0.8.0",
+  "description": "A fast, transparent, config-first terminal coding agent",
   "type": "module",
-  "packageManager": "bun@1.3.13",
+  "license": "MIT",
   "bin": {
-    "mc": "bin/mc.ts"
+    "mini-coder": "bin/mini-coder.ts"
   },
   "scripts": {
-    "dev": "bun run bin/mc.ts",
-    "check": "bun run lint && bun run typecheck",
-    "lint": "bun run biome check .",
-    "typecheck": "bun run tsc -p tsconfig.json --noEmit",
-    "format": "bun run prettier --write *.md && bun run biome format --write . && bun run biome check --write ."
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
-    "@types/bun": "^1.3.14",
-    "prettier": "^3.8.4",
-    "typescript": "^6.0.3"
+    "start": "node src/cli.ts",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cel-tui/components": "^0.8.3",
-    "@cel-tui/core": "^0.8.3",
-    "@earendil-works/pi-ai": "^0.79.3",
-    "diff": "^9.0.0",
-    "simple-git": "^3.36.0",
-    "yaml": "^2.9.0"
+    "@earendil-works/pi-ai": "0.87.0",
+    "@tree-sitter-grammars/tree-sitter-markdown": "0.3.2",
+    "diff": "^8.0.2",
+    "tree-sitter": "0.25.1",
+    "tree-sitter-javascript": "0.25.0",
+    "tree-sitter-typescript": "0.23.2",
+    "typebox": "1.3.27"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3"
   }
 }