Codegraff · How it works01 / 17

A technical walkthrough · August 2026

graff

Created byRach Pradhangithub.com/justrach/codegraff ↗

How one small agent loop becomes an evidence-driven execution-and-evolution system.

one Zig binaryprovider-neutraltools + workers

01 · What it is02 / 17

graff is the local runtime around the model.

It owns the model → tool → result loop, then gives that same loop to workers when the task earns them.

ShipOne native Zig executable; v0.0.238 downloads are about 1.8–1.9 MiB.
ReuseRoot and workers instantiate the same Agent with fresh history.
AdaptProvider wire formats and tool catalogs sit around the loop.
PersistRuns leave local JSONL; promotion evidence is content-addressed.

Lightweight describes the runtime, not the learning budget. A default two-arm prompt trial is roughly 180 short model runs.

02 · The core03 / 17

The loop keeps going until the work is done.

One Agent owns the history. Every provider response is normalized into the same question: finish, or call another tool?

  1. 01AskSerialize for the selected provider
  2. 02ActRun requested tools in parallel
  3. 03ReturnAppend results to the same history
  4. 04ContinueRepeat until completion

Root responses stream. Long histories compact around the selected model's context limit.

03 · Parallel work04 / 17

The root and every worker run the same Agent.

A worker gets fresh context and a precise brief, then runs the same model–tool loop to completion.

Explore

Find evidence without flooding the root context.

Implement

Change the files and report the exact paths.

Verify

Check the diff and return grounded results.

04 · Code intelligence05 / 17

CodeDB finds the code. Graff decides what to do with it.

When installed and indexed, Graff redirects supported code searches to CodeDB. The file picker falls back to a local walk.

  1. 01Indexsymbols + deps
  2. 02Routeword → prefix → trigram
  3. 03Verifysource lines
  4. 04Returnsmall context block
CodeDB in Graff
Structural retrieval; Graff owns execution, orchestration, and evolution
Codex
OpenAI coding agent across CLI, IDE, desktop, and cloud
Grok Build
SpaceXAI terminal agent with file, shell, web, headless, and ACP

Different layers: CodeDB retrieves context. Codex and Grok Build act. Graff uses CodeDB as an optional accelerator.

05 · Model routing06 / 17

Provider choice is separate from the control plane.

The agent loop does not care whether a turn uses an API key, a subscription login, or the hosted gateway.

WireAnthropic · OpenAI-compatible · Responses
AuthAPI key · bearer · subscription
SeatExplicit choice · persona · learned policy · ladder
graff route <model>

Dry-run the same provider and billing resolution a real session will use, without making a model call.

06 · Ultracode07 / 17

Buy only the orchestration the task earns.

Ultracode is an admission policy now, not an unconditional order to fan out.

R0Solo1–2 known files
R1ScoutExploration would flood context
R2Fleet3+ independent workstreams
R3FullAudit-class work + judges

The gate looks at cheap observables before anything spawns: named files, plan width, budget, audit language, and prior failure.

07 · Work landing08 / 17

A fleet has to land work, not merely discuss it.

01

Collapse duplicates. Near-identical briefs with the same worker genome spawn once.

02

Reserve the landing. Evidence cannot consume the budget needed to implement and verify.

03

Require a diff. An implement phase that changes nothing becomes an error and gets one retry.

04

Retry honestly. Workers retry bounded transient failures in place; hard caps fail immediately.

08 · Durable context09 / 17

Constraints survive because they live in the project.

Conversation memory compacts. The playbook does not.

Hard constraints

User-stated, root-visible, never silently widened.

Learned insights

Advisory bullets proposed after successful evals and curated by deterministic code.

The file is read when each brief is assembled, so fresh workers and fresh sessions inherit the same rules.

09 · Evolution, plainly10 / 17

Evolution is variation under evidence.

Graff proposes a child prompt, then the harness makes parent and child face the same work before either can become active.

What evolvesOne prompt becomes a candidate child.
  • Seeded mutation changes one behavior
  • Lineage and prompt fingerprint stay attached
  • The candidate starts with no authority
How the harness judgesParent and child run the same cases and seeds.
  • Critical regressions veto the child
  • Correctness ranks before cost
  • Only the primary-suite winner sees the holdout

Promotion is separate: verified evidence, every gate, then safe activation with rollback.

10 · Evolution authority11 / 17

Codegraff evolves two things, and keeps their authority separate.

Two local evidence paths feed two governed loops.

Prompt genomeChanges the root system prompt
  • Mutate → paired primary suite
  • Sole winner → independent holdout
  • Verified promotion + rollback
Orchestration policyChanges rung and model seat
  • Folds landed outcome rows
  • Task × budget × model stratum
  • Explicit choices never vote

Same machine, separate evidence and authority. Worker retry is reliability, not evolution.

11 · Evolutionary archive12 / 17

Evolution begins with a lineage you can audit.

Every run records which prompt produced which outcome, so improvement can be compared instead of guessed.

LineageParent → child edges preserve every turn and worker.
GenomeA prompt fingerprint exposes inherited and mutated variants.
EvidenceTool traces and score provenance attach outcomes to each branch.

The archive is inspectable and replayable. It records candidates; it never activates them.

12 · Prompt evolution13 / 17

Prompt evolution compares parent and child on the same work.

graff learn runs seeded mutations, paired evaluation, and a sole-winner holdout before activation.

  1. 01Parent
  2. 02Seeded mutation
  3. 03Paired evaluation
  4. 04Verify + holdout
  5. 05Activate / reject

A normal run only recommends. Automatic promotion needs configured enablement, --auto, every statistical gate, and the holdout.

13 · Why the gates exist14 / 17

Every gate blocks a concrete way self-improvement can lie.

Luck

Pair the conditions. Parent and child face the same case and seed; repetitions stay inside one statistical unit.

Regress

Veto critical loss. One parent-pass / child-fail on a critical case rejects the candidate.

Overfit

Hide a final test. Only the primary winner sees the independent holdout.

Stale

Bind the evidence. Immutable objects must match the exact active parent transaction.

Overbuy

Charge escalation. A higher rung owes +0.05 quality and p90 budget fit; trade-down only has to be no worse.

Correctness gates run before cost. Latency is reported, never promotion evidence.

14 · Orchestration learning15 / 17

Orchestration learning changes the route, not the prompt.

A landed turn teaches which rung and model seat can handle a similar phase within budget.

  1. 01Execute
  2. 02Outcome
  3. 03Local archive
  4. 04Policy cell
  5. 05Next route

This fold cannot mutate the root prompt. Explicit model or provider choices always win.

15 · Control16 / 17

The system narrows power at every boundary.

Root

State-changing actions pass an approval gate.

Files

Built-in file tools remain confined to the working tree.

Workers

Fresh workers receive a deliberately smaller tool surface.

Embedder

Local tools can be disabled and supplied by a sandbox MCP server.

terminal · desktop · JSON/SDK · HTTP serve · ACP/MCP

16 · Measured result17 / 17

Smaller orchestration produced a better result.

Old ultracode80mean score · 133 calls
Escalation ladder100mean score · 44 calls

1.22× the single-agent call baseline · zero budget deaths

Codegraff's deterministic five-eval study; project-reported, not an independent benchmark.

The loop stays small. Prompt and route improve through separate gates.