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