xonecas.io
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.