graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Repository instructions
Public tracker: bare minimum, no internals, no attribution
This repository is public. Issues, pull requests, commits, comments, and their edit histories are visible to everyone.
- Never post internal details. No private-repo paths or links (website,
frontend, gateway, zigrepper), no asset or deploy names, no infrastructure or
performance numbers, no session/run ids, no trace or transcript excerpts, no
local paths (
~/…), no quoted user messages, no provider/model/account details. Nothing from.graff/traces, sessions, or tool results. - An issue is the bare minimum: a generic symptom, the harness's own error text, the root cause in code terms, and the fix. Evidence stays in the conversation, not the tracker. Same for PR bodies and commit messages.
- No assistant or model-vendor attribution anywhere — not in issues, PRs,
commit messages, or trailers. No OpenAI/Anthropic/Cursor/session links. Commits
still use the repository owner's git identity as Author. When graff makes the
commit,
Co-Authored-By: Codegraff <[email protected]>is allowed (and is the only allowed trailer). Omit it if the user says not to. - If something sensitive was already posted, delete it (
gh api graphqldeleteIssuewith the node id fromgh issue view N --json id); editing is not enough because edit history stays visible. Then tell the user what was exposed and for how long.
Issue format: every report states its versions
Every issue, whether a person or an agent files it, opens with this header. A report without versions can't be told apart from a bug that a newer release already fixed.
**graff:** 0.0.302.25 (latest: 0.0.302.25)
**Harness:** 0.2.109, or "not used"
**Surface:** Harness | terminal | `graff -p` | ACP client | SDK
**Platform:** macOS arm64 | Linux x64 | Windows x64 | ...
## Symptom
What went wrong, in generic terms, with the tool's own error text verbatim.
## Repro
The smallest sequence of steps that shows it.
## Root cause
In code terms (`file.zig::function`), naming the tag or commit the line
numbers come from. Leave this section out if the cause isn't known.
## Fix
The expected behavior, or the proposed change.
- graff: run the binary that hit the bug. Harness runs its managed copy,
not the
graffonPATH:~/.harness/bin/graff --version(macOS and Linux). For the latest release, rungh release view --repo justrach/codegraff --json tagName. - Harness: on macOS, run
plutil -extract CFBundleShortVersionString raw /Applications/Harness.app/Contents/Info.plist. - If the graff that failed is older than the latest release, check whether the release notes or a closed issue already cover the bug. Reproduce it on the latest release before filing, or say plainly in the header that it wasn't rechecked.
- Cite source from a named version. If a report cites code from a local
checkout that isn't the running version, it describes code that may already
have changed. Use
v0.0.302.25:src/x.zig:93(or a commit hash), never a bare line number. - Search before filing. Search open and closed issues by the error text. Comment on an existing issue only when you have a new repro or diagnostic.
- What the header must not contain: model or provider names, account details, or paths. The public-tracker rules above still apply.
Keychain: never dump it
Never run security dump-keychain (with or without -d), and never walk every
keychain item. macOS pops an unlock dialog per secret and floods the desktop.
To check one named notary profile, use
security find-generic-password -l <profile-name> or read the documented
default from the release scripts. Do not pkill security/securityd.
Imported conversations continue in graff
A conversation brought in from another agent (Claude Code, Codex, or any other)
continues in a graff session, on graff's configured provider (for example
Codegraff). The source agent's transcript is read-only input. Never re-launch or
--resume the source agent to continue it, and never spend that agent's
subscription or credits. This applies in the REPL, over ACP, and in Harness.
Decisions live in docs/adr/
Settled, evidence-backed decisions are recorded as ADRs. Read the one-line index in docs/adr/README.md before changing behavior a record covers; what looks like an easy improvement may be a measured regression (see ADR 0001 on structured outputs). When your change settles a new load-bearing decision, add a record in the same branch.
Terminal UI: what's ours to change
- Colors, bold/dim, glyphs, layout are ours. Styling travels in the output byte stream as SGR escape sequences, so the app controls it per character. The palette lives in
src/ansi.zig(the line REPL follows Harness's Codegraff Dark theme: amber#e8a33d, cream text, and warm neutrals; coral/red hues are reserved for errors). - The font is not ours. The terminal emulator owns the typeface — it loads the font, measures the cell grid, and rasterizes glyphs itself; the wire protocol has no sequence for an app to request a font. (xterm's legacy
OSC 50is unimplemented by modern emulators and would hijack the user's whole terminal — do not emit it.) If a user asks to "change the REPL font," the answer is their terminal's config, e.g.font-family = Geist Mono(the site's typeface) in Ghostty — never a code change here. - HDR/wide-gamut color is not ours either. Truecolor SGR is 8-bit sRGB per channel — the protocol's ceiling; no sequence expresses Display P3 or EDR headroom, and macOS terminals clip app colors to SDR regardless of the panel. Pick values that look right on both P3 and sRGB displays (as
#059669does); that's the whole lever.
Separate terminal UI
The fullscreen terminal UI is maintained separately. graff tui launches an
installed graff-tui executable (beside graff first, then on PATH); it does
not download one. Keep UI rendering tests in that project. This repository
owns the engine, line REPL, ACP protocol, and external-launcher boundary.
File size
- Keep every hand-written source file at or below 600 lines of code.
- When a change would push a file past 600 LOC, split cohesive responsibilities into focused sibling modules as part of the same change.
- If a touched file is already over 600 LOC, do not grow it; move it toward the limit before adding more behavior.
- Generated files, vendored dependencies, lockfiles, and machine-produced artifacts are exempt; change their generator or source instead of hand-editing them.
Engine features are the same on REPL and ACP
Messaging (peer_message, idle peer mail, Accord live wake) and other
engine-side behavior (turns, tools, compaction, goals) must work the same on
the line REPL and ACP clients such as Harness (graff acp) and the separate
terminal UI. Surface
chrome can differ; the engine path cannot. If you add a wake, a latch, or a
delivery rule, wire it through the REPL and ACP engine paths in the same change.
The desktop app is Harness, which lives in its own repository and drives graff over ACP. A new-chat folder rule, a worktree handoff, or a session cwd that exists only in a client is not done — wire the same behavior through the ACP session in the same change. The workspace the agent runs in is not chrome.
Running tests
- While you work, run only what you touched:
zig build unit -Dtest-filter="<part of a test name>"builds and runs just the unit tests (repeat the flag for several names). zig build testalso runs the subprocess integration scripts and takes several minutes. Run it once before you push; the pre-push hook does.
nanocua: this repo holds the original
apps/nanocua is graff's computer use on macOS (ADR 0314), its own package with its own zig build test, pinned to a nanoui release. graff links none of it. nanoui's apps/nanocua is generated from this one by scripts/vendor-nanocua.sh and keeps this repository's license; change it here and copy it there, never the reverse.
Tests must be reachable
zig build testonly runs the tests in files the test root pulls in. A new module'stest {}blocks compile to nothing until something references it, and the suite still reports green.- A new test-bearing module needs a reference in
src/main.zig'stest {}block:_ = @import("your_module.zig");. - Prove it with the count, not with hope: the suite total must go up by the number of tests you added.
scripts/eval-tier1.sh --only reachfails on any file that declares tests nothing imports.
Merging pull requests
If asked to merge open PRs onto the release branch, merge only that branch. Do not merge them into main unless that was explicitly asked.
gh pr merge uses the PR's base, which is usually main. That is not landing on release/v…. Cherry-pick or merge the PR head into the named release branch instead.
Release branch beta versions
The newest numeric release/vX.Y.Z or release/vX.Y.Z.W branch is the beta
source. Compare numeric components, treating a missing fourth component as
zero; do not use lexical branch order or assume releases always have three
components. Every push to the current branch builds a unique
v<branch-version>-beta.<workflow-run>.<attempt> prerelease from that exact
commit. A queued build must recheck the remote branch and commit before it
publishes. Older release branches and superseded commits cannot replace the
latest beta.
Beta releases are GitHub prereleases and must explicitly remain outside the
stable latest pointer. The stable tag workflow is restricted to numeric
stable tags. The beta CLI release has no installer; download the versioned
tarball from the specific prerelease.
Before you push
Install the tracked hooks once, and the checks run themselves:
scripts/install-hooks.sh
That points core.hooksPath at .githooks/, whose pre-push runs tier 1 of the internal eval set: zig fmt, the 600-line ceiling, test reachability, zig build, the unit suite plus a count that may grow and never shrink, the named goal/loop/todo invariants, SDK drift, plus the terminal regression checks. It is deterministic and offline (no provider calls, no network, no spend). A warm fmt/reach/sdk subset is seconds; a post-src change rebuilds zig and runs the PTY probes, which is minutes (see #641). Prefer scripts/eval-tier1.sh --only <check> for a local edit. A push that only touches docs skips it.
scripts/eval-tier1.sh # run it by hand
scripts/eval-tier1.sh --only sdk # rerun one check
scripts/eval-tier1.sh --only fmt,reach # a comma-separated list (#641)
scripts/eval-tier1.sh --list # the check names
git push --no-verify # emergency skip (GRAFF_SKIP_PREPUSH=1 also works)
Failures name the invariant, say which regression it guards, and print the command that reruns only that check. The required invariants and the docs-only path list are data in scripts/eval/tier1-manifest.json.
Two rules the hook enforces that are easy to trip:
- The suite count is a ratchet. If it drops, either restore the tests or lower
test_count_baselinein the manifest in the same commit, with a reason in the message. Nothing raises it for you: bump it at each release cut, and tier 1 warns once the real suite has run more thantest_count_slack(25) tests ahead of the floor, because a floor that far behind would not notice a whole module falling out of the test root. - The SDKs are generated, not written. Run
python3 sdk/generate.py --harness ./zig-out/bin/graffafter any change to the model catalog, tool schemas, or provider list, and commit the result.
Tier 2: model-backed behavior
Behavior regressions do not show up in a unit suite. Tier 2 runs the harness for real, so it is opt-in and never in the hook. Cases are data in evals/harness_behavior.jsonl, one line each, carrying the regression it guards. The model is scripted (scripts/eval/mock_model.py), so the default run is offline and free.
python3 scripts/eval-tier2.py # every case
python3 scripts/eval-tier2.py --list # the cases and what they guard
python3 scripts/eval-tier2.py --only <id>
python3 scripts/eval-tier2.py --dump <id> # every event and request from one case
Add a case when you fix a behavior bug: script the model replies that provoke it, then assert on the events the harness emitted or on what it sent back to the model. Run it against a real provider with --provider/--model when you care how the model behaves rather than how the harness does.