xonecas.io
79113
Ma

mini-coding-agent / files

mini-coding-agent / AGENTS.md

3.2 KB
1# mini-coding-agent (`mini` for short)
2
3A fast, transparent, config-first terminal coding agent written in Zig.
4
5The source code is the source of truth for behavior. If a fact can be learned
6by reading the code, it does not belong here; keep this file short.
7
8## Guardrails
9
10- Minimalist by design.
11- Lightweight! Single binary, fast to boot and low memory usage.
12- No sandbox or permission layer. Tools run with the user's permissions;
13  isolation is an environment concern (`nono`), not the agent's.
14- No loop limits. No max turns, tool calls, token budgets, or agent-imposed
15  timeouts. The user's ability to interrupt is the limit.
16- Config-first. Every user-facing behavior that can vary comes from config with
17  a sane default. Global config only — no project-local config, no
18  config-override flags.
19- Minimal context. The model sees the configured system prompt plus explicitly
20  opted-in resource files — never reminders, hidden blocks, or harness
21  meta-text.
22- The agent never imports the TUI. Headless and TUI are two projections of the
23  same agent events; the TUI owns no agent or provider semantics.
24- Sessions are append-only JSONL, one message per line, fsynced on write. Never
25  rewrite or delete committed lines. A persistence failure stops the turn.
26- The loop has no compaction, no retries, and no meta-messages between steps.
27  Provider errors surface as-is, never masked or summarized. A failed request
28  is a rolled-back transaction: it never enters the context or the log, so the
29  user retries it by resending the turn unchanged.
30- `edit`, `read`, and `bash` only. Tool arguments are untrusted and validated
31  once at the boundary. `read` returns image blocks only for models that declare
32  image input.
33- Interruption: ESC politely pauses at the next step boundary; Ctrl+C cancels
34  the turn (abort the request, kill the tool's process group, persist the
35  aborted message); Ctrl+D exits on an empty draft. Completed side effects are
36  never undone.
37- Trace the real data flow before designing; apply guards at the narrowest
38  boundary.
39- Validate untrusted input once at the boundary, then keep internal code
40  plain-typed.
41- Ask before adding a dependency.
42- Do not add tests unless explicitly asked; verify manually.
43- We are the maintainers of this codebase, treat it with care and attention to detail.
44
45## Verification
46
47**Do not stand up mock servers, fixture endpoints, replay files, throwaway scripts, or mock
48terminals**; they prove nothing.
49
50Use a real bash call for headless runs, and the `tools/stress.sh` script for TUI
51runs.
52
53### Provider
54
55- Bash env has `OPENCODE_API_KEY` available.
56
57Verify against the real provider. Use the `OPENCODE_API_KEY` environment
58variable and a `config.json` that declares the provider under test.
59
60- Never edit the user's config unless explicitly asked.
61
62Use these models:
63
64- `openai-completions` -> `opencode-go/deepseek-v4.1-flash`
65- `openai-responses` -> `opencode-go/gpt-6-luna`
66- `anthropic-messages` -> `opencode-go/minimax-m3`
67- `google-generative-ai` -> `opencode/gemini-3.8-flash`
68
69### Driving the TUI with kitty
70
71There is no `tmux` here. `tools/stress.sh` drives the TUI in a real kitty
72window. Make sure to review both screenshots and text output.