graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.282 (2026-08-31)
Next cut after v0.0.281 merged to main (#670). The
headline is three yxlyx product PRs that were open against the old
main tip: atomic paste spans, terminal Codex WS errors, and
recoverable HTTP client generations.
281 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 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.
Resilience is engineered, not hoped for. This cut is largely the
transport hardening that keeps a whole workday alive: TLS client
generations rotate on a poisoned construction (ADR 0048), a Codex
type:error frame is honored as a terminal API answer instead of a redial
(#693), deterministic short flakes on the Codegraff seat retry twice while
auth and quota stay fail-fast (ADR 0053), and lean one-shots bounce a
prose-only fake completion (ADR 0052).
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 (see the frontier below) — without a 4-tool catalog or a 1 GB heap (ADR 0024).
Sessions are durable and forkable. Every conversation autosaves to
.graff/sessions; /resume restores provider history, and this cut adds
clone-on-write branches — --resume SOURCE --branch DEST forks a saved
session once and the two lives never write each other's files again
(ADR 0049). The GUI sidebar is the same directory.
A learning loop that runs itself. Sessions record behavior metrics; a workspace that does real model work bootstraps its own learning store once, detached so teardown never waits on suite generation; 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 Codex-class harness introduced in 281 (files pane, git Changes
review, per-tab agents, session-history sidebar) — unchanged here, it rides
the same ACP wire.
Atomic pasted-text placeholders (#674 / #673)
The composer used to store a long paste body out of band and represent it with ordinary editable text. Submit searched for the exact display string and replaced every match, so Option+Backspace chewed the marker word by word and a typed lookalike could resurrect a hidden body.
readline now owns a semantic paste store: each collapsed
[Pasted text #N +L lines] chip is a positional span. Navigation and
deletion treat it as one unit. Expansion happens only for a live span
and consumes its identity, so a typed lookalike stays literal. History
replay drops identity (history has no hidden body to restore).
readline_replay.zig holds history replay so readline.zig stays
under the 600-line ceiling.
Codex WS type:error is a terminal API response (#693 / #692)
Codex sends a useful type:error frame and then closes the socket.
Graff recognized only two special codes as terminal; a generic error
waited for another frame, treated the expected close as transport
loss, discarded the API body, and redialed. Users saw Bad Request
and the fullscreen TUI replaced the failure with an API-key row.
Every authoritative Responses type:error is now a terminal API
response. A bounded single-line provider/code/message diagnostic
rides last_api_error (no raw envelope). A stale
previous_response_id rebuilds full input exactly once. Generic
deterministic API errors return immediately and do not consume the
WS-retry / SSE-fallback ladder.
Model HTTP client generations (ADR 0048 / #694 / #691)
TlsInitializationFailed at std.http.Client.request happens before
a Request exists, so the #177 connection-poison path cannot mark
anything closing. Retrying the same launch-owned client left every
later TUI turn failing until process restart.
Model HTTP constructors lease an active launch-level generation. A
construction TLS failure retires that generation and publishes a
prewarmed replacement. In-flight callers keep the retired generation
through reference-counted leases; later retries resolve the original
launch pointer to the replacement. The original launch client is never
reclaimed by the manager (unrelated launch consumers still hold its
pointer). WebSocket transport stays independently managed. The two
production constructor catches share one predicate now: a handshake that
dies mid-read — on Windows an aborted peer surfaces as error.Unexpected
(NTSTATUS LOCAL_DISCONNECT), not TlsInitializationFailed — traverses
the same recovery, so the malformed-peer contract holds on every platform.
#694 recorded this as ADR 0042. That number is already TUI claims
screen on main. This cut remaps the record to 0048. The follow-up
hardens lease teardown (drain on shutdown, retry accounting, child
coverage) and keeps 0048.
Clone-on-write session branches (ADR 0049 / #697 / #689)
Two processes resuming the same name wrote the same .session.json.
--resume SOURCE --branch DEST (and /resume … --branch) clones
provider history and the peer cursor once; later saves belong only to
DEST. A filesystem-exclusive claim stops a destination race. Branches
do not auto-merge. #697 numbered this 0042; remapped to 0049. #698 reopened the
same head with three follow-ups now on this tip: raise the learn-pin
ceiling to 160 MiB so a Linux debug image still pins after session
branching linked in, match source suffixes at a token boundary so a
compaction handoff's .session.json / .transcript.jsonl is not a
JavaScript nudge, and parse Codex compaction user text from either a
chat string or Responses input_text blocks.
Warmed TLS on MCP HTTP and WSS (ADR 0050 / #679)
MCP probe/initialized stay on the persistent HTTP client. WSS CA is
scanned once per process. WS→SSE keeps the prewarmed pool. MCP HTTP
accepts gzip catalogs. #679 numbered this 0043; remapped to 0050.
Empty tool catalog is omitted (#695)
A wide-native RLM showcase that invalidated the root catalog and did
not rebuild it serialized "tools":, and every provider 400'd
(reproduced on 0.0.280). Showcase callers rebuild now; buildBody
also omits the field when the catalog string is empty — the same
shape text_only already uses. Responses, Chat, and Anthropic
bodies are pinned.
12-task in-house remasure after #697
Same SuperGrok seat, jobs=1, grok-4.6, x_search on. Graff is still
the unique frontier vs grok-build and OpenCode on pass / wall / calls /
tokens / list$ / RSS (run-20260831-021035-composite). Calls stayed
52. list$ ticked down. Wall is +9s vs the 141658 pin, almost all on
one model-variance retry of atomic-symlink-write. peer-resume
(the #697-shaped fixture) passed. First-token is not a named win.
Sandbox teleport and snapshot GC (ADR 0051 / #677)
Leftover of #554. /teleport <id> [docker|container] restores a
captured docker_image_tar onto another CLI backend. Apple Container
is the second backend (same wire, different bin_name). Dest defaults
to container when the live backend is docker or nothing is attached.
/snapshot gc [n] keeps the newest n snapshot trees (default 1).
The conversation is never rewound. Missing CLIs explain, they do not
crash. #677 numbered this 0042; remapped to 0051.
DeepSeek thinking-off and lean 15s bash (ADR 0052–0055 / #675)
Hillclimb of DeepSeek flash SWE on the Codegraff seat. Do not steal Pi's four-tool catalog or OpenCode's ~1G heap.
- Lean
-pbounces a first-turn prose-only "done" (ADR 0052). - Short Codegraff follow-up flakes retry twice (ADR 0053), including
the 110-byte
invalid_request_error/ "Body must be valid JSON". Auth / quota / a real invalid prompt stay fail-fast.opencode-codegraffis the same-seat OpenCode A/B harness. - DeepSeek family default low sends
thinking.type=disabled(ADR 0054)./effort highstill thinks. GLM stayslow-only. - Lean
-pbash auto-backgrounds at 15s (ADR 0055). Interactive stays 120s (ADR 0026).
#675 numbered these 0048–0051. 282 already owns 0048–0051; remapped
to 0052–0055. Keep-alive-only bodies share the short-flake retry
in agent_gateway_retry.zig so 282's request-scratch split stays.
We are the Pareto frontier — remeasured on this tip
Same SuperGrok seat, same 12 shipped-PR fixtures, jobs=1, grok-4.6,
x_search on — re-run against this exact release tip (b1fcf67, session
branches and the empty-catalog omit included). Every axis named is
lower-is-better, and graff is still the unique frontier on all of them
(run-20260831-021035-composite):
| harness | pass | wall | calls | tokens | list$ | RSS |
|---|---|---|---|---|---|---|
| graff | 12/12 | 200.9s | 52 | 230k | $0.34 | 8.8M |
| grok-build | 12/12 | 387.7s | 64 | 1.17M | $1.05 | 160.9M |
| OpenCode | 12/12 | 310.4s | 81 | 737k | $0.93 | 1149.9M |
Calls stayed exactly 52 and list price ticked down ($0.3504 → $0.3410)
with session branching in the tree. Wall is +8.8s vs the 281 pin, almost
all of it one model-variance retry on atomic-symlink-write — not a
regression. peer-resume (the fixture shaped like #697 itself) passed and
got faster.
For scale, the spine loop you feel per keystroke was 3/3 in 19.9s / 0.6s first / 8 calls on the same seat. Full tables, methodology, and the prior pin: graff-evals/hillclimb/baseline.md. How: the stable cache prefix, the RLM + spec-ptc loop, slim tool results, and the hardlink learn pin. We do not steal grok-build's heap or a 4-tool catalog to win (ADR 0024).
Parked
#277 (Streamable HTTP OAuth / Smolify) and #200 (idle localhost
servers) were closed as abandoned vs tip; the issues stay inventory in
yxlyx-leftovers.md. Smolify is not a reserved
core MCP.
Tests
This cut raises the release-cut floor to 1861 (slack 25). Paste
spans, Codex WS errors, HTTP generations, session branches, MCP
TLS-reuse, empty-catalog omit, teleport/GC, and DeepSeek/lean-bash
tests land on top of the 1804 floor from 281. The suite count is
re-ratcheted after zig build test on this revision.
agent_request.zig split request-scratch helpers into
agent_request_scratch.zig so the Codex WS merge stays under the
600-line ceiling.
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.282/install.sh | bash
Both macOS binaries are Developer ID Application signed (hardened runtime,
timestamped) and Apple notarized (notary-local, Accepted:
28299935-b4c5-48ca-916d-d03e04e1e021 aarch64,
0fdbb93f-ddb4-4424-8135-a37acd92a11c 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.