xonecas.io
79113
Ma

mini-coding-agent / commit eccdc11

chore: Docs review and fixes

xonecas2026-10-04 eccdc1148375732998e693667c00293a719cdea0 parent 37c6375

10 files changed

AGENTS.md+5−18
@@ -1,7 +1,6 @@
11 # mini-coding-agent (`mini` for short)
22
33 A fast, transparent, config-first terminal coding agent for one user at a time.
4-A careful Zig port of mini-coder.
54
65 This file holds intent, direction, and guardrails — not a description of the
76 code. The source is the source of truth for behavior. If a fact can be learned
@@ -19,18 +18,6 @@ by reading the code, it does not belong here; keep this file short.
1918 Node, no `node_modules`, no post-install scripts, no supply chain beyond what
2019 the code needs.
2120
22-## Provenance
23-
24-This project is a port. Its references are behavioral and structural, not
25-templates to copy:
26-
27-- `../mini-coder/` — the TypeScript implementation. The behavior specification.
28- Port its behavior, never its code.
29-- `../tiny-c-agent/` — a careful C port of the same design. The detail reference
30- for the low-level work: the four wire protocols, streaming reassembly, diff
31- capture, UTF-8 and base64 handling, session durability. Consult its structure
32- and its comments when porting those layers.
33-
3421 ## Direction
3522
3623 Deferred, not rejected. Do not build unless explicitly promoted:
@@ -56,8 +43,8 @@ Hard constraints. Do not cross these without explicit direction:
5643 full-screen cell grid.
5744 - **The provider layer is in-tree.** Implement the wire protocols directly —
5845 `openai-completions`, `openai-responses`, `anthropic-messages`,
59- `google-generative-ai`. Never depend on another harness's provider code.
60-- **Write original code.** `../mini-coder/` is a behavioral reference only.
46+ `google-generative-ai`. Never depend on an external provider library.
47+- **Write original code.** Copy nothing from another project.
6148 - **No sandbox or permission layer.** Tools run with the user's permissions;
6249 isolation is an environment concern, not the agent's.
6350 - **No loop limits.** No max turns, tool calls, token budgets, or agent-imposed
@@ -68,7 +55,7 @@ Hard constraints. Do not cross these without explicit direction:
6855 a provider's catalog or env vars.
6956 - **Minimal context.** The model sees the configured system prompt plus
7057 explicitly opted-in resource files — never reminders, hidden blocks, or
71- harness meta-text.
58+ injected meta-text.
7259 - **The agent never imports the TUI.** Headless and TUI are two projections of
7360 the same agent events; the TUI owns no agent or provider semantics.
7461
@@ -98,8 +85,8 @@ Hard constraints. Do not cross these without explicit direction:
9885
9986 ## Memory
10087
101-The port's reason for existing is that manual memory bookkeeping was the C port's
102-largest fragility. Do not reintroduce it.
88+Manual memory bookkeeping is the largest fragility a program of this shape can
89+carry. Do not reintroduce it.
10390
10491 - One allocator, chosen at startup, threaded explicitly. Long-lived state and
10592 per-turn scratch are separate lifetimes, not one global pool.
README.md+5−1
@@ -1,7 +1,11 @@
1-# mini
1+# mini-coding-agent
22
33 A fast, transparent, config-first terminal coding agent.
44
5+<p align="center">
6+ <img src="preview.png" alt="mini TUI" width="931">
7+</p>
8+
59 ## Build
610
711 Requires Zig 0.16.0.
preview.png+0−0
Binary file, not shown.
src/config.zig+1−1
@@ -55,7 +55,7 @@ pub fn configPath(a: std.mem.Allocator) []const u8 {
5555
5656 /// `$XDG_STATE_HOME/mini-coding-agent/sessions`, else
5757 /// `$HOME/.local/state/mini-coding-agent/sessions`, else the relative
58-/// `sessions`. Paths are not mini-coder's cwd-relative default.
58+/// `sessions`.
5959 fn sessionsDir(a: std.mem.Allocator) []const u8 {
6060 const state = platform.getEnv("XDG_STATE_HOME") orelse blk: {
6161 const home = platform.home() orelse return "sessions";
src/diff.zig+4−4
@@ -1,5 +1,5 @@
1-//! Unified diffs, matching `createTwoFilesPatch(path, path, before, after, "",
2-//! "", { context: 3 })` from the `diff` package. Display-only.
1+//! Unified diffs: an `Index:` line and a `---`/`+++` header pair, then hunks
2+//! with three lines of context. Display-only.
33
44 const std = @import("std");
55
@@ -27,8 +27,8 @@ fn splitLines(a: std.mem.Allocator, text: []const u8) ![]Line {
2727 return out.toOwnedSlice(a);
2828 }
2929
30-/// The `diff` package is line-based on raw text, so a final line without a
31-/// newline is a different line from the same text with one.
30+/// A line is its text plus whether it ended with a newline: a final line
31+/// without one is a different line from the same text with one.
3232 fn lineEq(x: Line, y: Line) bool {
3333 return x.nl == y.nl and x.p.len == y.p.len and std.mem.eql(u8, x.p, y.p);
3434 }
src/tools/index.zig+1−1
@@ -1,7 +1,7 @@
11 //! The tool set: schemas handed to the model, and dispatch to implementations.
22 //!
33 //! A name in the config that has no implementation is not advertised to the
4-//! model, so a request can never reach a tool the harness cannot run.
4+//! model, so a request can never reach a tool that cannot run.
55
66 const std = @import("std");
77 const config = @import("../config.zig");
src/tui/highlight.zig+6−5
@@ -164,8 +164,8 @@ fn predicatesPass(a: std.mem.Allocator, query: *const ts.Query, match: ts.Query.
164164 return true;
165165 }
166166
167-/// The C query parser stores a predicate's name without its leading `#`, so
168-/// every comparison here is against the bare name.
167+/// tree-sitter stores a predicate's name without its leading `#`, so every
168+/// comparison here is against the bare name.
169169 fn evalPredicate(a: std.mem.Allocator, query: *const ts.Query, match: ts.Query.Match, name: ?[]const u8, args: []const ts.Query.PredicateStep, u: Utf16, text: []const u8) bool {
170170 const n = name orelse return true;
171171 if (std.mem.eql(u8, n, "eq?")) return eqText(query, match, args, u, text);
@@ -486,9 +486,10 @@ pub fn formatTables(a: std.mem.Allocator, text: []const u8) []const u8 {
486486 return out.items;
487487 }
488488
489-/// The reference binding feeds every grammar UTF16LE and reports offsets in
490-/// UTF16 code units; the grammars' scanners parse input without a final line
491-/// ending differently per encoding, so the port feeds the same one.
489+/// Every grammar is fed UTF16LE, so a node's offsets are UTF16 code units and
490+/// not UTF-8 byte offsets. The choice matters: the markdown block grammar
491+/// reports an ERROR for input with no final line ending in UTF-8, and parses
492+/// that same input in UTF-16.
492493 const Utf16 = struct {
493494 units: []u16,
494495 /// One byte offset in the UTF-8 text per code unit, plus a final end entry.
src/tui/render.zig+3−2
@@ -1,7 +1,8 @@
11 const std = @import("std");
22
3-/// East-Asian-width plus combining/zero-width rules, mirroring the TypeScript
4-/// `charWidth`. Combining marks use the common Unicode mark ranges.
3+/// The cell count one code point occupies on screen: two for an East-Asian
4+/// wide code point, zero for a combining or zero-width one, one otherwise.
5+/// Combining marks use the common Unicode mark ranges.
56 pub fn charWidth(code: u21) u8 {
67 if (code < 32 or (code >= 0x7f and code < 0xa0)) return 0;
78 if (code == 0x200b or code == 0x200c or code == 0x200d or code == 0xfeff) return 0;
src/types.zig+2−1
@@ -1,4 +1,5 @@
1-//! Provider-neutral transcript types, mirroring pi-ai's message shapes.
1+//! Provider-neutral transcript types: what a message is, before any wire
2+//! protocol encodes it.
23 //!
34 //! A tool call's arguments are kept as their raw JSON object text, exactly as
45 //! the provider streamed them, so provider continuation data survives a
src/util.zig+0−1
@@ -98,7 +98,6 @@ pub fn randomBytes(buf: []u8) void {
9898 }
9999
100100 /// The byte length of a valid UTF-8 sequence at the start of `p`, or null.
101-/// Ported from the C reference so decoding is identical there and here.
102101 fn utf8SeqLen(p: []const u8) ?usize {
103102 if (p.len == 0) return null;
104103 const c = p[0];