Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
13.8 KB
Raw Blame

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 acp child, 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/sessions directory — 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 · Review bar 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

Pareto frontier, 12 in-house fixtures: wall and tool calls vs list price — graff lower-left

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.

Pareto frontier, 6-task in-house run

3-task spine (run-20260830-124315): graff 3/3 in 19.9s / 0.6s first / 8 calls — the loop overhead you feel per keystroke.

Pareto frontier, 3-task spine

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.