graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.284 (2026-09-01)
Next cut after v0.0.283 merged to main. The headline is
the native/ACP surfaces behaving like the REPL: pasted images actually
reach the model, a peer wake no longer hijacks a greeting, /resume
finds the sessions you saved from $HOME, and a named-source nudge
stops replaying the same question for the rest of the day.
283 stays published as-is. This is not a retag.
What this cut is
graff is still one static Zig binary that turns the AI subscriptions you
already pay for into an agent on your machine — same Agent type on the
line REPL, the fullscreen TUI, graff acp, and the native GUI. 284 is
the cut that closes the gaps those surfaces hit in production:
- an ACP client (the native app) could attach an image and the model
only ever saw
@[path]text - a parked peer message made a two-word greeting spend the turn in
peer_message /resumelooked empty if you had saved from$HOME- naming
SPEC.mdonce re-armed a source-file gate on every later turn - a typed TUI
/goalnever retired, so/resumesteered the next unrelated prompt at finished work workspace listcould not select a tree because the row did not own its path bytes
Those are all closed. The in-house 12-task remasure on this tip is a unique Pareto against grok-build and OpenCode (wall included).
Pasted images reach the model through ACP clients
An image attached from an ACP client (the desktop/native chat surfaces)
arrived at the model as literal @[path] text; the pixel payload was
never staged, so vision turns silently lost the image. The ACP turn
path now runs the same promotion the mainloop and REPL already do —
@[image] markers stage into native provider vision blocks, and the
message is built from the staged queue. Non-image @[path] entries
stay literal text so the agent still opens them with its tools. Queued
prompts are covered: the attachment block is baked in at submit and
queued prompts drain through the same turn path. One regression test
covers both the image and non-image cases.
Peer wake is advisory, not a command (#708)
The one-line [peer] wake appended to a user turn ended in the
imperative peer_message action=inbox, so a trivial turn (a bare
greeting) made the agent spend the turn reading the mailbox instead of
replying. The wake now says messages are parked and gives the read
hint inline as a when-relevant option, short enough to stay one
unwrapped dim row; an empty inbox carries no read command at all.
Detection is untouched (prefix-based), so compact/peek paths and
resumed transcripts are unaffected.
Invalid JSON after a failed parallel bash (#711)
A parallel bash pair that returned HTTP 404 left a tool result in
history, then the next Codex request failed with Invalid body: failed to parse JSON value. Send-time normalization now coerces
function_call.arguments and non-string function_call_output.output
to JSON strings before the body is built.
Device-wide /resume (#712 / ADR 0059)
Bare /resume and /sessions listed only .graff/sessions under cwd.
Saves from $HOME (~/.graff/sessions) looked like they were gone.
The picker and /sessions now show cwd first, then home, labeled with
origin. Resuming a foreign save restores conversation history into the
current cwd and says so — read_file / edit_file / bash do not
silently switch trees. New saves write a workspace field; legacy
files infer origin from the directory that holds them.
Named-source gate and turn replay (#714 / ADR 0060)
A user question that named a source file could replay for dozens of
turns. The nudge walked all history, so SPEC.md in an earlier
message re-armed the gate on every later completion, and
repl_convo.adopt appended the frontend's trailing user row even
when it was already the latest ask. The gate is now per unanswered
mention, kept on the Agent (not a process global). Identical user
injects are skipped; three copies fail closed. The same words after an
answer still run.
Fullscreen /goal retires on completion (#716)
A typed TUI /goal was published as a standing session flag, so
attempt_completion recorded the finish and left the objective
active. /resume restored it and the next unrelated prompt was
steered toward finished work. The pager now sends status / pause /
resume / clear through the same lifecycle as the line REPL;
typed goals stay non-standing.
Worktree rows own their path bytes (#715)
workspace list emitted rows whose path pointer did not outlive the
listing, so use could not select a tree that was visibly on the
list. Each row now owns its path / head / branch bytes. List and use
see the same strings.
Gateway is a fallback seat, not the startup default
Codegraff gateway was winning model election at boot even when a signed-in plan (Codex, SuperGrok, Claude) was the seat you actually pay for. The gateway is now a fallback: it is offered when the preferred seat is missing or exhausted, not as the first pick on a cold start. Matches ADR 0017 (signed-in plans first).
Mid-turn failover moves the provider label with the model
When a provider failed over mid-turn, the TUI updated the model name and left the old provider badge in the footer — so the chrome said one seat and the request was on another. The failover event now moves both labels together.
Alt-backspace deletes the previous word
The line composer and the TUI both treat Alt-Backspace (and the matching CSI-u) as delete-previous-word, the way a macOS text field does. Ctrl-U still clears to the start of the line.
In-house remasure — unique Pareto
Same SuperGrok seat, grok-4.6, jobs=1, x_search on, ReleaseSafe
graff-dev (33d28be). Composite run-20260901-121759-composite
(graff 11 from 121149 + atomic-symlink-write retried at 67.8s
after a 115.5s stall at the same 4 calls; grok 112552; OpenCode
112149). All three harnesses 12/12.
| harness | pass | wall | calls | tokens | list$ | RSS |
|---|---|---|---|---|---|---|
| graff | 12/12 | 219.6s | 53 | 234k | $0.32 | 8.7M |
| grok-build | 12/12 | 489.8s | 60 | 1.12M | $1.07 | 155M |
| OpenCode | 12/12 | 234.8s | 77 | 675k | $0.68 | 1.0G |
Unique frontier on pass / wall / calls / tokens / list$ / RSS.
Wall beats OpenCode by 15.2s. First-token is not scored. Do not close
later gaps by dropping x_search or shrinking the catalog (ADR 0024 /
0031). An earlier same-seat graff draw (241.6s) lost wall and is not
this pin.
Full methodology and earlier pins: graff-evals/hillclimb/baseline.md.
Tests
Suite floor stays 1882. This fold adds the #711 / #712 / #714 / #715 / #716 cases on top of the ACP-image and #708 work already on the branch. Cutting this release also merged v0.0.283's #701 ACP pre-auth and #707 Alt-nav so they are not dropped off main.
Downloads
All six CLI archives, the curl installer, and checksums:
| File | Platform |
|---|---|
| graff-aarch64-linux.tar.gz | Linux arm64 |
| graff-aarch64-macos.tar.gz | macOS Apple Silicon — Developer ID signed, Apple notarized |
| graff-aarch64-windows.tar.gz | Windows arm64 |
| graff-x86_64-linux.tar.gz | Linux x86_64 |
| graff-x86_64-macos.tar.gz | macOS Intel — Developer ID signed, Apple notarized |
| graff-x86_64-windows.tar.gz | Windows x86_64 |
| install.sh | curl installer |
| SHA256SUMS | checksums for the six archives |
curl -fsSL https://github.com/justrach/codegraff/releases/download/v0.0.284/install.sh | bash
Both macOS binaries are Developer ID Application signed (hardened runtime,
timestamped) and Apple notarized (notary-local, Accepted:
37f8d140-90df-4a3a-ae82-f151196be2b3 aarch64,
2129fac3-7954-4615-a033-a8fdba9a9149 x86_64). Stapling is skipped on
the bare CLI (stapler error 73); Gatekeeper checks the ticket online at
first launch. GitHub also attaches the usual source zip/tarball for the tag.