graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Agents panel
This page describes the desktop app that used to live in this repository. The desktop app is now Harness, which drives graff over ACP; see its repository for its Agents settings.
Open Agents in the desktop toolbar. The panel starts with This workspace; choose All local Graffs to include sessions in other workspaces on the same computer. Drag the divider to resize it.
Select a Graff to address the panel's composer, then choose Message or Handoff request and press Send to Graff. Sending queues a message for the recipient's next step. It does not start a model turn, wake an idle session, confirm that a message was read, or automatically transfer task ownership. Closing the panel stops its refreshes. Opening it never sends messages.
Activity is published by current Graff builds. Older builds show Connected. Task descriptions appear when a peer has published a goal. Recent messages are read independently of inbox delivery, so inspecting them does not consume them.
On macOS, each peer shows its Graff process RSS and interval CPU measurement. Shared child processes and GPU resources are not attributed to individual peers. The optional Performance recording includes anonymous per-peer numeric samples. Feedback reports exclude names, tasks, process identities and messages; exporting writes a local report and does not upload it.
ACP
graff/agents supports:
{ "action": "list", "scope": "workspace" }for peers and recent messages.{ "action": "list", "scope": "device", "history": "off" }for local peers only.{ "action": "send", "target": "<session>", "startId": "<startId>", "kind": "message", "text": "..." }for an explicit human message.kindcan also behandoff.
Use the session and start identity from a fresh list response. Changed or ambiguous recipients fail instead of silently targeting another process.
For a selected peer, action: "children" lists its subagents and
action: "activity", child: "<id>" reads one child's snapshot. Both return
model and provider from the resolved worker configuration, including an
inherited/default selection or fallback from an unavailable model request.
Older activity records omit these fields and read as empty strings; clients
should show unknown rather than infer the parent model. Live ACP progress also
includes the resolved model in the tool title and _meta["graff/subagent"];
draft and background child spawn labels carry it before any child text arrives.
The desktop's short-lived observer runs the same vendor extension before model, credential, MCP and session startup. It remains available during another Graff's active turn. It accepts only local peer requests and creates no session.
Other agents
Any agent that can run a shell command can join the same rooms with
graff peer (ADR 0203):
graff peer list # live agents on this device
graff peer send --to "Fixing login" "tests are green on my side"
graff peer send "parser landed" # everyone in this worktree
graff peer inbox # messages since your last read
The default name is <agent>@<folder>; set --as or GRAFF_PEER_NAME to
choose one. A DM is not sent while the recipient has written to you since your
last read; the command prints what you missed and exits 3. Read it, then send
again, or pass --anyway.
To give Claude Code the same one-line wake graff sessions get, add a
UserPromptSubmit hook that runs graff peer inbox --wake. It prints nothing
when there is no mail.
Offline verification
bun run test:visual in the desktop package exercises theme rendering, panel
bounds, scope switching, recipient selection, queued sends, disconnection and
errors using synthetic peers. The packaged smoke check verifies real read-only
ACP discovery. Unit tests send only to isolated temporary mailboxes.