graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Use Codegraff as an MCP tool and app
Automatic HTTP setup
The CLI installer runs graff mcp install. If graff came with the desktop
app, Harness, run graff mcp install yourself once. Setup
requires Python 3 (Python 3.11+ to validate Codex TOML), and macOS launchd or
Linux user systemd.
Setup starts a shared service at http://127.0.0.1:7720/mcp, creates a private
bearer token, and adds HTTP entries for detected Claude Code, Codex, Cursor,
Gemini CLI, Windsurf and VS Code installations. Installer-owned entries refresh on later installs while unrelated entries and
user-modified Codegraff entries are preserved. Malformed or JSON-with-comments files are
left unchanged with a diagnostic. Restart clients to load their new entry.
Clients that require stdio can use the manual configuration below.
The default workspace is your home directory; tasks remain approval-gated. To choose a fixed project and optional port, run:
graff mcp install --directory /absolute/path/to/project --port 7720
Subsequent installs retain that directory and port. Changing the port refreshes installer-owned entries; user-modified entries
remain yours to update. Service
installation restarts the managed listener, so finish active tasks first.
Run graff mcp install again to configure clients installed later.
Set GRAFF_NO_MCP=1 when running the CLI installer to skip automatic setup.
This does not stop a previously installed service. Stop/disable it using:
- macOS:
launchctl bootout gui/$(id -u)/dev.codegraff.mcp, then remove~/Library/LaunchAgents/dev.codegraff.mcp.plistto prevent login startup. - Linux:
systemctl --user disable --now codegraff-mcp.service.
Remove the codegraff entry from client configs if it is no longer wanted.
Run the HTTP listener yourself
export GRAFF_MCP_TOKEN="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
graff mcp serve --http --port 7720
Clients need that token in their Authorization: Bearer … header. The managed
service keeps its token in ~/.graff/mcp/token and writes the matching headers
into private client config files. The listener binds only to 127.0.0.1, checks
the Host and Origin headers, and exposes only /mcp. There is no public bind
or browser CORS access. The embedded UI is delivered through the MCP host.
POST accepts JSON-RPC and returns JSON, or HTTP 202 for accepted notifications.
A 2026-07-28 request is stateless: no session, and its MCP-Protocol-Version,
Mcp-Method and Mcp-Name headers must match the body (HTTP 400 with
-32020 otherwise; an unknown version gets HTTP 400 with -32022). For the
older revisions, initialization returns Mcp-Session-Id; later calls must
send it. DELETE closes
a session, and GET returns 405 (no SSE stream). The service retains up to 64
client handshakes, replacing the oldest on overflow; an evicted client gets
404 and must initialize again. Each client negotiates Apps support separately.
Tasks across clients run serially and share the listener; each task still gets
a fresh bounded child. HTTP saves duplicate listener startup, not model tokens
or the per-task model startup. Existing task limits still apply.
graff mcp serve exposes Codegraff's task runner to local MCP clients. The
client launches it over stdio, discovers run_task, and supplies a brief.
Each call runs a fresh Codegraff child in the server's launch directory and
returns its answer. Existing graff mcp add, list, and login commands
still configure the MCP tools Codegraff consumes.
Manual stdio configuration
Use an absolute path to the built or installed graff executable in your
client's MCP server configuration. For clients using mcpServers JSON:
{
"mcpServers": {
"codegraff": {
"command": "/absolute/path/to/graff",
"args": ["mcp", "serve"]
}
}
}
Set the server's working directory to the project using your client's cwd setting, or launch the client from that project. Calls cannot override cwd, credentials, permission mode, or arbitrary CLI flags.
Run graff login first for actual tasks. Initialization and tool discovery
work without credentials. Tasks inherit the launch environment and existing
Codegraff configuration. To pin a model, append --model NAME to the server
arguments; otherwise Codegraff uses its normal configured model selection.
By default tasks use --safe: permission-gated operations are denied when
there is no interactive approval channel. For unattended coding in a trusted
workspace, explicitly append --yolo to the server launch arguments.
This authorizes the ordinary Codegraff tools, including file edits, commands,
and configured MCP tools. It is not an OS sandbox; the client must approve
and scope task calls appropriately. Review resulting edits before integrating.
Call the tool
{
"name": "run_task",
"arguments": {
"prompt": "Explain how the configuration parser handles missing values. Cite the relevant files. Do not change files.",
"context": "We are on release/v0.0.292; the parser was rewritten last week and the old walker is gone.",
"timeout_seconds": 120,
"max_model_calls": 8
}
}
A useful brief includes the concrete task, permitted scope, and acceptance
criteria; background the child cannot re-derive goes in context. There is no
inherited client conversation: the child sees only what you pass. Prefer
small explanations, focused reviews, test runs, and narrowly scoped fixes.
prompt: required, nonblank, at most 32 KiB of UTF-8 text.context: optional background for the child — relevant history, decisions, file paths or constraints. Nonblank, at most 32 KiB of UTF-8 text. It is appended to the child's system prompt. At or below 8 KiB it is passed through verbatim; above that the server summarizes it first, because a fresh child cannot consume the gateway's opaque compaction state and a large handover would otherwise crowd out the task itself. Summarizing runs under the same credentials, so it bills to the same account, and it never touches the workspace: the summarizer runs--safewith no tool budget.timeout_seconds: 1–300, default 120. The summarizer's own deadline is capped separately at 60s and does not consume this budget.max_model_calls: 1–32, default 8, shared across the child invocation. The summarizer runs on its own single-call budget.- Root tool calls are capped at 64 per turn.
When Graff calls this tool over HTTP, its transport waits for the validated child budget, any required context summarization, and 15 seconds for cleanup and the final partial-output reply. Discovery and unrelated tools retain their normal deadlines. Other MCP hosts control their own transport timeouts: allow at least the task timeout plus 15 seconds, or plus 75 seconds when context exceeds 8 KiB. A shorter host timeout can discard the reply; it does not prove the child stopped, and this tool has no continuation handle.
context carries text only. It cannot set cwd, credentials, model, permission
mode, or any CLI flag — those still come from the server launch.
The MCP result contains text, isError, and schema-described structuredContent
with text, status, output_truncated, timeout_seconds, max_model_calls,
context_chars, context_summarized, context_used_chars, usage_reported,
usage_unavailable_reason, and preprocess. The last three context fields report the context
the caller sent, whether it was summarized, and how much text the child actually
received. If summarization fails the task is not run and the error says so,
rather than silently dropping the context.
The same object is also mirrored under _meta["codegraff/runTask"] on the tool
result, so a client that renders the raw result can show supplied-context size
and summarization state without parsing prose. Those facts also cross into ACP:
a completed tool_call_update carries _meta["codegraff/runTask"] (alongside
_meta["graff/view"] when the result opened a view), so an ACP client such as
Harness renders them the same way. Only the fields above travel — never the
task's text and never the caller's context.
Per-task usage and charge for the child's own execution are not reported.
usage_reported is always false, with usage_unavailable_reason naming the
cause: the task child runs in print mode, which exposes no settled gateway
charge, and a charge is never derived from list rates
(src/pricing_settled.zig). This is a known limit, not an unimplemented field —
account-wide gateway usage remains authoritative for what a task cost.
Preprocessing is reported, separately. When context had to be summarized,
preprocess carries cost_usd, usage_complete, input_tokens,
output_tokens and unavailable_reason. The summarizer runs as a --json
child — print mode reports no settled charge — with its one request line on a
file-backed stdin, so the engine's exact-charge ingestion supplies the number
and no pipe has to be fed concurrently. An incomplete report
(usage_complete: false, or any unpriced_calls / missing_usage_calls) yields
cost_usd: null with a reason; a list-rate estimate is never presented as a
settlement. Preprocessing is reported in its own object and never folded into
the child total, so it cannot be double-counted. When no summarization was
needed, unavailable_reason says so and the tokens are zero.
Status is completed, failed, timed_out, or cancelled. Process failures and deadlines
return an error with partial output; changes made before failure are not
rolled back. Successful exit reports the harness answer, not independent
verification of its claims. Answers are capped at 64 KiB and failure
diagnostics at 16 KiB, with explicit truncation markers.
Embedded task result
Hosts advertising io.modelcontextprotocol/ui with MIME type
text/html;profile=mcp-app receive UI metadata on run_task. The host reads
ui://codegraff/task-result and renders the bundled task panel in its sandbox.
It shows completion status, configured limits, truncation, the task brief, and
searchable output with a line-wrap control. Theme changes follow the host. The embedded conversation uses the desktop
palette from src/ui_theme.css, compiled into the MCP resource,
with the same task chrome, user bubble and response layout.
No extra server, package install, or network access is needed for the view. The panel is a result inspector: it does not run or retry tasks, stream progress, or change permissions. Submit follow-up tasks through the host conversation. Clients without the extension receive the ordinary tool with the same text and structured result. UI support depends on the host; MCP tool support alone does not imply embedded-app support.
The HTML requests no external domains or device permissions. Model output is rendered as literal text. Resources list/read expose only the bundled template, never workspace files or saved task data.
See the MCP Apps specification.
Lifecycle and limits
The server implements server/discover, ping, tools/list, tools/call,
resources/list, resources/read, and an empty resources/templates/list
using newline-delimited JSON-RPC on stdin/stdout.
- 2026-07-28 (stateless): each request carries its version and client
capabilities in
_meta; noinitialize. Results carryresultType, and discovery, list and read results addttlMsandcacheScope: "public". An unknown version gets-32022withsupportedandrequested. - 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05: the
initializehandshake, negotiating 2025-11-25 for an unknown revision.server/discoverwithout_metais method-not-found, so dual-era clients fall back.
See the MCP specification.
Calls run serially. This initial adapter has no progress stream, live
cancellation, session continuation, or background task handle.
Keep the client's tool timeout longer than timeout_seconds to receive the
terminal result. If a client disconnects during a call, the child can continue
until its deadline; the runner terminates its process tree on deadline.
The child inherits a recursion marker. A nested graff mcp serve launch is
refused, preventing a configured Codegraff server from recursively delegating
to itself. Each call starts fresh; unrelated environment and workspace
configuration still follow the ordinary harness behavior.
Run the offline integration check with python3 scripts/test-mcp-server.py
after zig build. It uses the local scripted model on port 1234.
For the embedded view regression, run node scripts/test-mcp-task-app.cjs
with @playwright/test resolvable and Chrome installed. It uses a
local opaque iframe and checks the handshake, presentation controls, themes,
mobile layout, text-only rendering, cancellation notification and teardown.
HTTP and setup checks: python3 scripts/test-mcp-http.py
and python3 scripts/test-install-mcp.py.