graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.281 (2026-08-29)
Next cut after tagged v0.0.280. The headline is the hardlink graff-pinned + detached learn init:
-p and the REPL share one path, no 127M copy. The earlier oneshot-only
skip is not the tip behavior. The README is short and carries the
same-model 12-task in-house frontier (#690).
280 stays published as-is. This is not a retag.
What graff is, and how it works
graff is one static Zig binary — about 3.7 MB, zero dependencies, its HTTP client brings its own TLS — that turns the AI subscriptions you already pay for into an agent that does work on your machine. You sign in with Codex, SuperGrok, Kimi, Claude, or any API key; you hand it a task in plain English; it plans, writes and runs code, edits your real files, and keeps going until the task verifies — including spinning up a team of subagents in parallel worktrees. You don't chat with it. You give it work.
One agent, many faces. A single Agent type is the unit of execution:
the line REPL's root, every subagent, graff acp's session, the embedded
libgraff/wasm engine (ADR 0038), and the TUI's in-process client (ADR 0041)
are all the same struct running the same turn loop. Nothing is re-implemented
per surface — a surface is a sink.
Many seats, one wire contract. Provider adapters decouple wire format
from auth style, so subscription logins and API keys are interchangeable:
ChatGPT OAuth speaks the Responses API (with server-side compaction that
carries the lossless compact blob, and a WebSocket turn transport), Claude
Code OAuth speaks Anthropic Messages, SuperGrok tokens speak xAI's Responses
wire over WebSocket with hosted x_search, and plain API keys speak OpenAI
Chat or Anthropic. A model election ranks signed-in plans above metered keys
on the same model (ADR 0017), so a flat-rate seat is what actually gets used.
The turn loop. buildBody serializes the request against a
stable prompt-cache prefix — the catalog, tool schemas, and skill list
are pinned so a warm cache hit survives every load — then streams the
response over SSE and normalizes everything into typed EngineEvents. Sinks
render those events; the REPL, --json stream, and TUI are proven
byte-identical against the same trace. Tool calls fan out on the Io thread
pool: built-ins (bash, edit_file/write_file/read_file — exact-string
replaces, path-confined), subagent and workflow (dynamic fan-out as
data), and MCP servers from .mcp.json (namespaced, schemas loaded lazily,
deferred past first paint). A structural permission gate sits under every
state-changing call — metacharacter-aware bash matching, cwd lock, path
confinement that /yolo cannot bypass — so autonomy is a dial, not a hope.
Context discipline is the product. The transcript is append-only and compaction cannot rewrite it (ADR 0021); OpenAI routes use first-party server-side compaction with a local transactional fallback; oversized tool results spill to a 4 KB handle the model can open instead of occupying context turn after turn; the RLM + mid-stream spec-ptc loop lets the model program over context instead of pasting it back into the prompt (ADR 0022). That stack is why the same model on the same seat below runs 2–6× cheaper and faster than peer harnesses at ~92M RSS — without a 4-tool catalog or a 1 GB heap (ADR 0024).
A learning loop that runs itself. Sessions record behavior metrics; a
workspace that does real model work bootstraps its own learning store once,
detaching graff init so teardown never waits on suite generation (the
-p change below); the kit pins the live binary by hardlink — no 127M
copy; generated suites and independent holdouts drive background tournaments
that promote a new genome only through statistical gates.
Surfaces. graff (line REPL), graff tui (the Grok-style fullscreen
pager), graff acp (Agent Client Protocol for Zed and the desktop apps),
@codegraff/sdk (TypeScript + Python, embeddable in-process or remote), and
two GUIs: the Tauri desktop app in gui/ with its auto-updater, and the
native harness below.
The new GUI: a Codex-class native harness
The native app (merjs desktop shell — Zig → ObjC → NSWindow + WKWebView,
no Electron — over Beautiful UI primitives) grew the pieces that make it a
real harness instead of a chat window, this cut:
- One agent per tab. Each chat tab owns its
graff acpchild, keyed<page>:<chat>so a reload never adopts a stale agent; tabs run turns concurrently, and closing one reaps its agent after it writes its exit save. - graff's own session history in the sidebar. The sidebar is the
workspace's
.graff/sessionsdirectory — every conversation, REPL or native, bucketed by day and searchable. Opening one renders its saved transcript immediately and resumes it, so a follow-up continues with the model's memory intact. - A files pane and a Changes review. The files pane walks the agent's
cwd with breadcrumbs, a text viewer with gutter and wrap, and inline
images. After editing turns, a Codex-style
Changed N files +A −D · Reviewbar surfaces the real git diff. - A live model picker backed by
graff --models: authenticated seats with election order, type-to-filter, and current-model sync after a respawn. - It reads like an AI app now. Assistant markdown streams through a zero-dependency renderer with clickable workspace paths; text drains at a backlog-proportional pace instead of arriving in chunks; thinking carries a duration stamp and shimmer, running tools tick a wall-clock counter, the active tab pulses while its turn works, and the send button morphs into a stop.
We are the Pareto frontier
Same grok-4.6, same SuperGrok seat, same shipped-PR fixtures. Every axis named is lower-is-better, and graff is the unique frontier on all of them.
12 shipped-PR fixtures (run-20260830-141658, --suite inhouse):
| harness | pass | wall | calls | tokens | list$ | RSS |
|---|---|---|---|---|---|---|
| graff | 12/12 | 192s | 52 | 228k | $0.35 | 92M |
| grok-build | 12/12 | 462s | 63 | 1.18M | $1.12 | 170M |
| OpenCode | 12/12 | 236s | 74 | 675k | $0.79 | 1.1G |
6-task in-house Pareto run (run-20260830-122731): graff 6/6 in
164.7s / 0.7s first token / 26 calls, vs grok-build 530.9s and OpenCode
168.4s.
3-task spine (run-20260830-124315): graff 3/3 in 19.9s /
0.6s first / 8 calls — the loop overhead you feel per keystroke.
Full tables and methodology: graff-evals/hillclimb/baseline.md. How: the stable cache prefix, the RLM + spec-ptc loop, slim tool results, and the hardlink pin + detached init below. We do not steal grok-build's heap or a 4-tool catalog to win.
One-shots skip learn auto-init (ADR 0044 / #668)
Every graff-dev SWE task used to make exactly 5 API calls (the
learn_auto bootstrap floor) and then startBackgroundLearning copied
.graff/learn-kit/graff-pinned and generated suites — 38s of local
CPU per task. Tokens and calls already matched Pi.
startBackgroundLearning is now a no-op on -p / --json. Interactive
REPL / TUI / ACP still auto-init after 5 model calls.
GRAFF_LEARN_AUTO=off still kills the whole trigger. graff learn init
is unchanged.
Confirm (graff-evals/results/run-20260829-031139.jsonl, SuperGrok
grok-4.6, --suite swe -j 6):
| pass | wall | CPU | sandbox | |
|---|---|---|---|---|
| before (ADR 0043) | 4/6 | 456s | 230s | 127M pin |
| after | 5/6 | 205s | 6.5s | 100–164K |
Wall −55%, CPU −97%, same tokens/calls (~160k / 30).
json-stream passed this rep (the model kept “no RS → empty”); the
earlier Pi 5/6 vs graff 4/6 was one-rep noise on the same SPEC clause
ADR 0024 already named. label-sort still fails — grok-build and Pi
miss it too. RSS ~91M is the process, not the pin.
Do not steal Pi's 4-tool catalog or 165M heap.
TUI claims the screen before boot (ADR 0042 / #666)
graff tui / TTY graff repl claim the alt-screen before credentials
and leftover MCP/prompt work. Kitty/mouse/paste stay on run's single
enable_seq. Live markdown paints on the cached tail. Welcome stays
empty. Off a TTY the claim is a no-op.
Pi on the SuperGrok seat (ADR 0043 / #667)
pi-xai maps ~/.xai/credentials/graff-oauth.json into XAI_API_KEY
and execs stock pi -p --mode json --provider xai. Fair A/B is
--suite swe --harness graff-dev,pi-xai --model grok-4.6. Keep Pi on
stock defaults.
GLM 5.3-flash on the Codegraff gateway (ADR 0045 / #669)
Same suite after the skip, CODEGRAFF_API_KEY →
gateway.codegraff.com/v1, --model glm-5.3-flash (uncatalogued, so
it falls through; do not pass glm-5.3, that row is zai).
| harness | pass | wall | RSS |
|---|---|---|---|
| graff-dev (thinking on) | 3/6 | 1353s | 90.5M |
| pi-codegraff | 5/6 | 758s | 167M |
graff-dev (low, #671) |
5/6 | 286s | 91M |
Flash default effort is low; -p streams (ADR 0046 / #671)
Omitting reasoning_effort still bills thinking (27 reasoning tokens
on a pong; SWE streamed 1.9MB reasoning_content). low bills 0.
none is a 400. /effort high still sends. Root -p uses postLive
so a hung gateway dies on the 30s head-stall, not a 5-minute
postWatched. Same miss as Pi (label-sort). Do not steal Pi's
catalog or heap.
Same suite on DeepSeek / Gemini / Kimi (ADR 0047)
Same seat (CODEGRAFF_API_KEY, graff-dev vs pi-codegraff,
--suite swe -j 6). GLM 5/6 in 286s was not a one-off on flash:
| model | graff | pi |
|---|---|---|
glm-5.3-flash (0046) |
5/6 in 286s | 5/6 in 758s |
gemini-3.7-flash |
5/6 in 103s | 0/6 (tool-loop dead) |
kimi-k2.6 |
4/6 in 583s | 2/6 (3× API zero) |
deepseek-v4-flash |
2/6 in 199s* | 5/6 in 492s |
*three 1-call no-edits; an isolated retry recovered map-conflict
and json-stream. Pi's Gemini column is not a fair A/B. Do not steal
Pi's catalog to "fix" DeepSeek. label-sort still fails everywhere.
TUI first paint no longer waits on companion MCP (#664)
Interactive --yolo queues codedb-pro onto pending_starts (same
defer as ADR 0035 MCP). codedb-pro probe is capped at 2s. A
defer_join fan-out that cannot io.concurrent skips that server
instead of inline io.async. Dim receipts after plugins: name the
next phase (mcp: N server(s) in background, companion: codedb-pro (background)). First paint is the welcome composer.
Mid-turn stalls stay off the transcript (#665)
Reconnect and inner-loop model call N pulses are bookkeeping
(ADR 0021). A ⚠ prints only when the turn actually ends (stream stalled — ending turn / connection dropped — response ended early).
■ interrupted, ↳ queued, and ↳ force stay.
yxlyx doctor / cube / governed / localhost stay inventory in yxlyx-leftovers.md.
Pareto product from #688
Named-file Responses nudge (input_text + Chat→typed coerce on resend),
catalog rebuild after a 4-wide native showcase (tools:, empty-array
bug), -p TTFT mark, SSE hold until the data payload, and the
chrome / MCP handshake / symlink fixture. Hardlink pin, detached
learn init, x_search on, and the oneshot learn skip stay.
In-house (run-20260830-122731): graff-dev 6/6 in 164.7s /
0.7s first / 26 calls vs grok 530.9s and OpenCode 168.4s.
Spine (run-20260830-124315): 3/3 in 19.9s / 0.6s first.
Tests
This cut raises the release-cut floor to 1804 (slack 25). #688 adds the named-file nudge, catalog-rebuild, and MCP handshake pins on top of the 1791 floor (#668 / #671 / #664 / #665 / #687 / #666).
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.281/install.sh | bash
Both macOS binaries are Developer ID Application signed (hardened runtime,
timestamped) and Apple notarized (notary-local, Accepted:
84d66403-8220-4f05-af4a-1ebbdc6a1753 aarch64,
70e824aa-becd-403a-a48c-00628f5a823a 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.