holy shit @ivanleomk i used @GoogleDeepMind’s gemma4(with codegraff) on the flight to Japan to read through a few papers i was interested in and it cooked!!(i think it just needs a really good harness)

https://t.co/IksPGvhY5p (pre-release) https://t.co/yWyH0VKlCr

justrach/codegraff

Source: https://github.com/justrach/codegraff

graff

An AI that actually does the work. Not just talks about it.

Install it on your Mac or Linux machine, sign in with the AI subscription you already have, and hand it real tasks. graff writes and runs code, automates the boring stuff, digs through your files, researches the web, and runs its own experiments, on its own, until the job is done.
You don't chat with it. You give it work.

curl -fsSL https://github.com/justrach/codegraff/releases/latest/download/install.sh | sh

_{Prefer a window? Grab the desktop app. Then just run graff and tell it what you need.}

What can I ask it?

If you could do it at a computer, you can ask graff to do it for you:

• “Build me a little app to track my workouts.” It writes it, runs it, and shows you.
• “Turn this folder of messy CSVs into one clean spreadsheet.”
• “Figure out why my site is slow, then fix it.”
• “Scrape these five pages and summarize them.”
• “Run an experiment: try three versions of this and tell me which scores best.”

It works in your real terminal, on your real files, with the real internet, and it can spin up a whole team of sub-agents to work in parallel. It even keeps score of which approaches work and gets better over time.

Don’t write code? You don’t have to. Say what you want in plain English; graff figures out the steps and does them.

How it compares

Run the same job on graff, Claude Code, and Codex (three read-only questions about this repo, plus an 8-trial latency test), and here is what it means for you:

Your AI bill is a fraction. graff runs the same task on whatever model fits your budget. On deepseek-v4-pro it averaged 0.022 per task**, against Claude Code's **0.51 (Opus 4.8) and Codex’s $0.42 (gpt-5.5). That is roughly 20× cheaper, because Claude Code only runs Claude and Codex only runs GPT, while graff runs deepseek, kimi, glm, grok, minimax, gpt, claude, and more. On the same model the token usage is comparable, so the win is the freedom to pick a cheaper one, not a token trick.

It stays out of your way. graff is one 1.7 MB Zig binary. In these runs it used about 25 MB of memory for focused work (more when it reads a lot of code), against Claude Code’s steady ~410 MB (Node) and Codex’s ~206 MB (Rust). Leave it running next to everything else and your laptop won’t notice.

Scripts and CI finish in half the time. For one-shot runs (graff -p, the SDKs, a CI step), graff completed a gpt-5.5 turn in 4.4 s versus Codex’s 8.9 s on the identical ChatGPT endpoint, on every single trial. That is graff’s near-instant startup beating a heavier per-call launch. In a long interactive session the startup amortizes and both settle to model latency, so this is a one-shot and automation win, not a blanket “graff is faster.”

_{Method: macOS, same machine, read-only code questions on this repo. Cost is each tool’s own reported usage at codegraff gateway prices; memory is peak RSS via /usr/bin/time -l; latency is 8 concurrent graff/Codex pairs on a tool-free prompt with reasoning effort matched. Your numbers will vary with the task, the model, and the network. Reproduce it yourself: benchmarks/.}

Install

Desktop app: macOS (Apple Silicon)

Prefer a window over a terminal? Download the latest signed, notarized build, drag it to Applications, and open it. The desktop app is fully self-contained: it bundles the graff agent, so there’s nothing else to install to start coding, and it keeps itself up to date automatically. On first launch it drops two commands on your PATH: codegraff <path> (opens that folder in the app, code-style) and graff itself (the agent CLI, in your terminal), so the one install covers both the window and the command line. The terminal graff is symlinked into the app, so it auto-updates along with it. Not on Apple Silicon, or want a standalone CLI? Use the command-line install below.

_{or browse all releases}

Command line: macOS · Linux

Grab the latest prebuilt release binary: macOS builds are Developer ID signed and Apple notarized; on any other platform the installer builds from source with Zig 0.16:

curl -fsSL https://github.com/justrach/codegraff/releases/latest/download/install.sh | sh

From a checkout, just run ./install.sh. The binary lands in ~/bin by default (override with HARNESS_DIR):

Give it a key

Three ways, pick whichever is easiest:

graff login                     # free codegraff key (device-code OAuth, no signup forms)
graff key set deepseek sk-...   # store ANY provider's key (macOS Keychain, else 0600 file)
export DEEPSEEK_API_KEY=sk-...  # or just an env var (env always wins)

Already logged into the Codex CLI? Skip this step. Your ChatGPT subscription is picked up automatically from ~/.codex/auth.json. Or run graff login codex.

Note on login: there is no per-provider login command. graff login is specifically the free codegraff key, and graff login codex is the ChatGPT-subscription OAuth. Every other provider (deepseek, openai, anthropic, kimi, xai, zai, minimax, xiaomi) is a key: set it with graff key set <provider> <key> or its <PROVIDER>_API_KEY env var, then select a model with --model / /model. See Providers & models.

Run it

graff                            # starts on the first provider you have a key for
graff --model deepseek-reasoner  # or pin one explicitly

First things to try once you’re at the › prompt:

› what's in this directory? summarize the build setup.
› /model sonnet                  # fuzzy-switches to claude-sonnet-4-6
› spawn three subagents to summarize src/, count TODOs, and check git status, in parallel
› ultracode audit this repo for error-handling gaps   # codeword → multi-agent workflow mode
› /help                          # everything else

Why

Measured, not vibes: arm64 macOS, ReleaseFast; methodology and the budgets each change is held to live in architecture.md:

Benchmarked against the Rust codegraff (justrach/codegraff, 39 MB binary, 934 crates) on the same model through the same endpoint, interleaved 3×: turn speed was a dead tie (2.94 s vs 2.93 s; the network and the model dominate the turn), but the Zig harness ran in 4.3× less memory (11.3 MB vs 48.5 MB), starts 3.5× faster, and is 23× smaller on disk. An agent CLI rarely wins on turn speed; it can win on the cost of being there.

Code intelligence: token-efficient by default

The fastest way to blow a context window is to read whole files into it. graff ships with a built-in codedb tool: read-only, structural code intelligence over a local index of the repo (github.com/justrach/codedb), and the system prompt steers the model to reach for it before grep or whole-file reads. Instead of paying for a 2,000-line file to find one function, the model asks for exactly the shape it needs:

codedb outline src/main.zig          # just the symbol map, functions/types, no bodies
codedb symbol switchProvider --body  # one function, by name
codedb callers recordUsage           # who calls it (call sites, not files)
codedb search "parse SSE"            # indexed search, ranked hits, not a grep dump
codedb context "add a new provider"  # task-shaped orientation across the codebase

Why this keeps token cost low:

• Structural slices, not files. outline/symbol/callers/deps return a function map or a single definition, tens of lines where a read_file would spend thousands. The index is queried, not the raw bytes streamed into history.
• It’s free and indexed; the metered tools come second. The system prompt encodes an explicit search order: try the free, indexed codedb first; fall to (metered) muonry/raw search only for literal/regex or non-indexed files. The cheap path is the default path.
• Hard output cap. A query is truncated at 64 KB with a marker that nudges the model back toward targeted queries (outline, symbol --body) rather than whole-file reads, so even a broad search can’t balloon the context.
• Same index powers the @ file picker (codedb glob), so attaching a file by name never shells out to a directory walk.

Pure-Zig client to a pure-Zig server, zero dependencies on either side. Allowed subcommands: search · symbol · callers · find · outline · read · tree · context · word · deps · glob · ls · file · hot. Not installed? The tool says so and points at the one-line install; everything else keeps working without it.

An evolutionary harness

graff doesn’t just run an agent; it records every run as a node in a Darwin Gödel Machine-style archive tree (arXiv:2505.22954), so the harness itself is the substrate for agent self-improvement. Each session appends to harness.trajectory.jsonl (truncated per session, like the trace):

• A lineage tree, not a flat log. Root turns form a spine (each turn’s parent is the previous one); every subagent and workflow task hangs off the turn that spawned it. Each node carries a fingerprint of the system prompt it ran with (prompt_sha = first 8 bytes of SHA-256), so prompt mutations ( set_system_prompt on the spine, per-child system_prompt overrides on the fan-out) show up as hash changes along edges. A lineage can be replayed or scored offline.
• Personas are variants. Subagents pick a persona with agent (built-ins: reviewer · researcher · implementer · skeptic, plus anything in .harness/agents/) or take a custom system_prompt; either way the trajectory records the lineage, so you can mine which agent variant actually worked.
• A fitness ledger with integrity. The score channel appends evaluation records (prompt_sha, score, parent_sha; the lineage edge DGM parent selection counts children with). Because the archive lives in the working directory, a forged score row could manufacture fitness, so every score the harness writes is HMAC-signed (keyed by GRAFF_SCORE_KEY_FILE, a secret outside the cwd that the evolving agent’s confined tools can’t reach). Readers recompute the HMAC and reject unsigned or forged rows. Signing is opt-in and backward-compatible (no key → unsigned, accepted as before).
• Tool-use is mined too. Each agent logs its tool calls (name + error flag, in order): the process signal behind “which tool combinations work”, joinable to scores via prompt_sha.
• Closed loop in releases. Release binaries ship anonymous evolution telemetry (opt-out) so agent-variant fitness is learned across the fleet, not just one laptop. /trajectory renders the current session’s agent tree; see docs/hyperagents.md for the full design.

Providers & models

Six API-key providers plus a subscription login, three wire formats. A ProviderSpec table (provider_specs in src/main.zig) holds each provider’s endpoint, auth style, env var, and default model; base URLs and key names come from models.dev’s api.json (snapshot 2026-06-10).

Using a specific provider directly is always the same two steps: give it the key, then name a model. For example, DeepSeek straight to api.deepseek.com:

graff key set deepseek sk-...          # or: export DEEPSEEK_API_KEY=sk-...
graff --model deepseek-reasoner        # models: deepseek-v4-pro · deepseek-v4-flash · deepseek-chat · deepseek-reasoner

The same pattern works for every API-key row above: swap in the provider id and one of its models (graff key set openai sk-... → --model gpt-..., graff key set anthropic sk-ant-... → --model sonnet, and so on).

A model is routed to the first provider (in the table order above) that both has a key set and lists the model in model_table. Unknown claude* models fall back to Anthropic; any other unknown model falls back to the codegraff gateway, and /model prints a warning when that fallback fires, since a typo’d name will be rejected by the API on the first request. The startup default is the first provider with a key, on its default model. /models prints the full table: context window, compaction point, provider, and which providers you have keys for; /model <name> switches (a bare /model opens an interactive fuzzy picker).

CLI reference

usage:
  graff [flags]                    start the REPL
  graff [-p] "prompt"              one-shot: run the prompt, print the answer, exit
  graff login                      get a codegraff key (device-code OAuth)
  graff login codex [--refresh]    ChatGPT/Codex OAuth login (PKCE)
  graff key set <provider> <key>   store a key (macOS Keychain, else 0600 file)
  graff key list                   show which providers have keys
  graff mcp add <name> -- <cmd>     add an MCP server to .mcp.json
  graff mcp                         list configured MCP servers
  graff --schema                   print the machine-readable interface (SDK codegen)

flags:
  --model <name>   start on this model (same fuzzy resolution as /model)
  --yolo           skip all permission prompts for the session
  -p, --print      one-shot print mode (answer on stdout, tool progress on stderr)
  --timing         show per-tool wall-clock on result lines (✓ (312ms) …)
  --cost           show running session spend in the prompt ([model · 12k tok · $0.0042])
  --json           structured stdio protocol (JSON in, JSONL events out, SDK transport)
  -h, --help       usage
  -V, --version    version

Unknown flags are an error (with a pointer to --help), a missing --model value is an error, and --help/--version are handled before subcommand dispatch, so graff login --help prints usage instead of starting an OAuth flow. With no key configured at all, startup fails with the three quickest fixes spelled out rather than a bare env-var list.

One-shot mode makes the harness scriptable without the SDK: graff -p "how many TODOs in src/?" runs a full agentic turn (tools included), prints only the final answer on stdout (progress lines go to stderr), and exits non-zero on failure. There’s no human to ask, so the permission gate denies anything not already allowed. Pre-approve commands in .harness/settings.json or pass --yolo.

REPL commands

A bare / opens the whole list as a filterable full-screen menu (type to narrow, Enter runs it); Esc during a response interrupts the turn: generation stops (it works from the moment the request is sent, including a slow provider connect), what already streamed stays in history with an [interrupted] marker, and you’re back at the prompt. A bare Esc at the prompt clears the input line.

While a response streams you stay in control: besides Esc to interrupt, Ctrl-T (^T) folds/unfolds the live “Thinking” block in place, and the mouse wheel scrolls your terminal’s own scrollback: the REPL doesn’t grab the mouse, so scrolling up to re-read earlier output works like any normal terminal (parity with Claude Code). Folding the Thinking block is keyboard-only (^T). There is no click-to-fold.

/model [name]   no arg → interactive fuzzy picker; or /model <name|provider|provider model>
/models         list known models, context windows, compaction points
/clear          wipe the conversation and start fresh
/plan           toggle plan mode: read-only explore + propose; writes/edits denied
/key [p k]      show API-key status; /key <provider> <key> adds one live (+ Keychain)
/keepcontext    toggle keeping the conversation when /model switches wire format (default on)
/reasoning      codex/gpt-5 reasoning depth: low|medium|high (default high)
/rewind [n]     list past prompts; /rewind <n> drops prompt n+after & reverts its file edits
/image <path>   attach an image to your next message (vision models only)
/paste          attach the clipboard image (macOS); also Ctrl-V (⌘V can't be captured)
/strict         toggle "every message is a tool" mode
/yolo           toggle bash auto-approval (skip permission prompts)
/trace          toggle the JSONL event trace (harness.trace.jsonl)
/compact        summarize history into a fresh context
/save | /resume | /sessions   session persistence; bare /resume → interactive picker
/todo           show the current task list
/mcp [add …]    list MCP servers/tools; /mcp add <name> <cmd> connects one live
/help           list commands
exit | /exit | ctrl-d | ctrl-c(empty)   quit

/plan, /yolo, and /strict change how the permission gate behaves for the session. See Permission modes.

The line editor supports ↑/↓ history (persisted to ~/.simple-harness-history), Tab completion (commands, and model names after /model ), and emacs-style editing (Ctrl-A/E/W/U/K, Option+Delete, word moves). The selected model is remembered in ~/.simple-harness-model and resumed next launch (--model <name> overrides; a remembered model that’s no longer in the table is ignored with a note). The prompt is a small statusline: [model · 12345/800k tok (1%) · ⚡cached · $0.0042]: context used vs the compaction budget, last cache hit, and session spend. Errors aim to be actionable: /resume nope says the session file wasn’t found and points at /sessions; an unknown /foo points at /help.

Permission modes

By default graff asks before doing anything that can change your machine. File writes (write_file/edit_file), MCP tool calls, and any bash command that isn’t read-only stop at a permission gate:

⚠ rm -rf build/
[y]es once · [a]lways allow "rm" (saved to .harness/settings.json) · [n]o ›

• y runs it once · a runs it and remembers the rule · n denies it (the model is told and picks another path).
• Always appends a prefix rule to .harness/settings.json under "allow", so that command never prompts again, this session or a future one. Pre-seed that file by hand to allow commands up front (it lives next to your hooks; the harness preserves the rest of the file).
• Read-only commands are auto-allowed and never prompt: ls cat head tail wc grep rg pwd which file, git status|diff|log|show, zig build|fmt, but only while every path stays inside the working directory (cat /etc/passwd still asks), and only as a plain command. A pipe, redirect, &&, or $(…) always prompts, so a second command can’t be smuggled past a prefix match.

Three session-wide modes change the gate. Set on the CLI, or flip them live in the REPL:

One-shot mode (graff -p "…" or --json) has no human to answer the prompt, so the gate denies anything not already allowed. Pre-approve commands in .harness/settings.json or pass --yolo.

SDKs: TypeScript & Python

graff is scriptable from your own code. graff --json is a structured stdio protocol (JSON requests in, JSONL events out; ask_user is answered with a structured {"type":"answer","text":"...","cancelled":false} line) and graff --schema prints the machine-readable interface, and the TypeScript and Python SDKs in sdk/ are auto-generated from that schema, so they never drift from the binary. On every release tag a GitHub Action rebuilds, regenerates, fails if the committed SDKs are stale, and publishes to npm (@graff-new/sdk) and PyPI (simple-harness-sdk).

# Python
from harness_sdk import Harness

with Harness(yolo=True, model="gpt-5.5") as h:
    print(h.ask("what is 2+2?"))
    for ev in h.chat("read foo.txt"):
        print(ev["type"], ev)

// TypeScript
import { Harness, runAgent } from "@graff-new/sdk";

// one-shot, streamed
for await (const ev of runAgent({ prompt: "summarize README.md", model: "gpt-5.5", yolo: true })) {
  if (ev.type === "text") process.stdout.write(ev.text);
  if (ev.type === "turn") console.log("\ncost $", ev.cost_usd);
}

// long-lived, multi-turn
const session = Harness.init({ model: "claude-opus-4-8", yolo: true }).session();
console.log(await session.ask("what files are here?"));
session.close();

Can’t spawn a local process (edge runtimes, browsers, other machines)? Run graff serve and both SDKs ship matching remote clients that drive it over HTTP: @graff-new/sdk/remote (fetch-only: Workers/Deno/Bun/browsers) and Python’s RemoteHarness (stdlib only). Same method surface, same event stream. See sdk/README.md.

Reference

{
  "mcpServers": {
    "codedb":      { "command": "codedb", "args": ["mcp", "."] },
    "everything":  { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"] }
  }
}

zig build run            # or: ./zig-out/bin/graff
zig build test           # the test suite (also run by CI, .github/workflows/ci.yml)

codesign --verify --strict --verbose=2 graff   # → valid on disk; satisfies its Designated Requirement
codesign -dv --verbose=4 graff 2>&1 | grep Authority
#   Authority=Developer ID Application: Rachit Pradhan (WWP9DLJ27P)

Coming soon

Active directions. See the Status & roadmap details above for the full list, and the GitHub issues for what’s in flight:

• Sandboxes. Run the agent’s bash/file tools inside an isolated sandbox (ephemeral container / microVM) so untrusted or destructive steps can’t touch the host. It’s the natural next layer above today’s cwd-confinement and permission gate, and the safe substrate for hands-off evolutionary runs.
• Closing the evolution loop end-to-end: a grounded judge, sync-back of fleet trajectories, and automatic promotion of winning agent variants.
• Windows support, shell completions + man page, and a config file for default flags/model.

License

codegraff is licensed under a modified GNU AGPL-3.0 (see LICENSE). The public receives it under the AGPL-3.0, so network use triggers the Section 13 obligation to make Corresponding Source available to remote users. The authors Rach Pradhan (justrach) and Yu Xi Lim (yxlyx) reserve full rights to use, distribute, and offer it (and modified versions) as a private, proprietary, or hosted/cloud product, free of those obligations.

A recipient’s AGPL-3.0 licence is perpetual and irrevocable unless they breach it: it can’t be withdrawn at will, which is what makes open use safe to rely on. Any proprietary or commercial permission to use codegraff without the AGPL’s copyleft is a separate thing, and exists only if both authors grant it jointly in writing. Such a permission is revocable at the authors’ discretion at any time, and neither the provision of consultancy or other services nor any side agreement grants it or makes it irrevocable. If it is revoked, the user falls back to full AGPL compliance or must stop using codegraff. For commercial or proprietary licensing, contact the authors.

_{Built in Zig 0.16 · AGPL-3.0 (modified) · architecture.md · uxlog.md}