graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
v0.0.268 (2026-08-20)
This release makes subagent personas files you can actually write, and closes the grok-build job loop that 0.0.267 started: live output, wait for exit, then a single notify instead of a poll.
Codex-shaped agent files
Personas used to be markdown with YAML-ish frontmatter. That still works,
and /agents promote still writes <niche>.md. You can now author the
same niche as a standalone TOML file, with the field names Codex uses:
name = "pr_explorer"
description = "Read-only codebase explorer."
model = "grok-4.6"
model_reasoning_effort = "medium"
isolation = "shared_cwd"
developer_instructions = """
Stay in exploration mode.
Cite files and symbols.
"""
Load order (later shadows earlier by name):
- compiled builtins
~/.codex/agents~/.harness/agents- plugin
agents/ .codex/agents.harness/agents- a verified learned policy
In one directory, .md loads first and .toml wins. Spawn is unchanged:
subagent agent:"pr_explorer". Pins still resolve spawn > persona file >
session default. sandbox_mode is accepted so a copied Codex file loads;
only worktree / shared_cwd mean anything to graff. Codex MCP/skills
tables in the file are ignored — those stay session MCP.
Templates live in docs/examples/agents/.
Live bash, then one notify
Foreground bash now emits 16 KiB bash_output_chunk frames the way
grok-build does. Those bytes go to a dedicated raw terminal buffer, not
the prose stream, so a ls does not interleave with the model's
sentence. When a background job exits, job_notify records a wake: the
next agent step sees it, and an idle TUI starts a turn. Combined with
ADR 0010 (wait-for-exit already in 0.0.267), the model should not poll
bash_output every 30s.
Cerebras Inference
graff key set cerebras csk-… (or CEREBRAS_API_KEY) adds the same
OpenAI-chat seat Groq already has, at https://api.cerebras.ai. Default
model is gpt-oss-120b; gemma-4-31b is the other offline catalog
entry. This is Cerebras Inference, not the WSE CSL kernel SDK.
Session resume and peer speech
/resume now restores the worktree/device room cursors and the parked
peer_message inbox (ADR 0014). A new process no longer re-drains the
last 10 JSONL lines into history. Peer wakes do not title or mint a
session. -p one-shots still join at the tail.
codedb list_dir is the directory listing (ADR 0013): in-process BFS,
gitignore, 10k cap — not a new always-on catalog tool.
Images in ask_user and compaction
Pasted screenshots in an ask_user reply used to arrive as [Image]
placeholders (#580). They now ride a follow-up user vision message after
the text tool result (ADR 0015). Compaction and emergency trim stop
before an unresolved current prompt so those blocks are not summarized
to text (#581). imagegen's Codex engine writes a private features-only
config.toml and only links auth.json, so codex exec no longer dies
on the user's MCP/skills overlay (#576).
Distribution
Prebuilt archives are available for Linux, macOS, and Windows on arm64 and
x86_64. Both macOS binaries are Developer ID signed, hardened-runtime enabled,
and notarized by Apple; SHA256SUMS covers all six platform archives.