Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Docs: point every desktop-app mention at Harness

justrach6c1f7b16a0ca
diff --git a/README.md b/README.md
index f197117a..5c633a53 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@
<p align="center">An AI coding agent for your terminal. One small binary, no dependencies.</p>
+<p align="center">Want a desktop app? <a href="https://github.com/justrach/harness"><strong>Harness</strong></a> runs graff with chat, review, files, and terminals in one window.</p>
+
<p align="center">
<img alt="macOS · Linux · Windows" src="https://img.shields.io/badge/macOS%20·%20Linux%20·%20Windows-555">
<img alt="One binary, 3.7 MB" src="https://img.shields.io/badge/one%20binary-3.7%20MB-44cc11">
@@ -37,8 +39,8 @@ curl -fsSL https://github.com/justrach/codegraff/releases/latest/download/instal
On Windows, unpack `graff-x86_64-windows.tar.gz` (or `aarch64`) from the
[latest release](https://github.com/justrach/codegraff/releases/latest) and put
-`graff.exe` on your `PATH`. The [desktop app](#desktop-app) installs `graff`
-for you.
+`graff.exe` on your `PATH`. The desktop app, [Harness](https://github.com/justrach/harness), installs
+`graff` for you.
```sh
graff login # sign in
diff --git a/docs/acp-client-parity.md b/docs/acp-client-parity.md
index 6db42087..5cb97822 100644
--- a/docs/acp-client-parity.md
+++ b/docs/acp-client-parity.md
@@ -1,5 +1,7 @@
# ACP client behavior and limits
+> Written against the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/harness), which drives graff over the same ACP surface.
+
The live `graff acp` process speaks [ACP v1](https://agentclientprotocol.com/protocol/v1/overview). The desktop is its client: it sends prompts and renders `session/update` notifications. A streamed tool row is identified by `toolCallId`; updates change that row, and a new `content` array replaces its prior content. The turn ends when the original `session/prompt` request responds with a `stopReason`, including `cancelled` after cancellation. [Tool calls](https://agentclientprotocol.com/protocol/v1/tool-calls) and [prompt turns](https://agentclientprotocol.com/protocol/v1/prompt-turn) define those wire rules.
The desktop restores its own saved chat view and starts a replacement agent with `--resume <name>`. Separately, a v1 client may use `session/load` when the live agent advertises `loadSession`: the session ID is a saved conversation name in the selected workspace, and the agent replays retained user messages, assistant messages, and tool results before responding. Replay is display history; it does not rerun tools or revive shell jobs. The live process owns one active session and rejects a second `session/new`; start another process for another session. The in-process embed has no durable store and does not advertise `loadSession`. [ACP session setup](https://agentclientprotocol.com/protocol/v1/session-setup) specifies the capability and replay order.
diff --git a/docs/agents-panel.md b/docs/agents-panel.md
index a94fcc18..02d54fcb 100644
--- a/docs/agents-panel.md
+++ b/docs/agents-panel.md
@@ -1,5 +1,7 @@
# Agents panel
+> This page describes the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/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.
diff --git a/docs/mcp-apps.md b/docs/mcp-apps.md
index 73d1bb8b..a8f72f79 100644
--- a/docs/mcp-apps.md
+++ b/docs/mcp-apps.md
@@ -1,5 +1,7 @@
# MCP Apps in Codegraff
+> This page describes the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/harness), which drives graff over ACP. Harness does not render MCP Apps views yet; the tool result text and images still reach the transcript.
+
Call a connected MCP tool that declares an MCP Apps UI. In the native GUI, its tool result includes an **Interactive MCP result** view. Close/reopen controls dispose and restore the view. Text and image output stays available in the transcript.
In the REPL, run **`/mcp apps`** after the tool completes to open its latest saved view in the default browser. The link in the tool result also identifies the standalone HTML file. This works with the existing MCP server configuration and consent process; it does not install or authorize additional servers.
diff --git a/docs/mcp-server.md b/docs/mcp-server.md
index 25db14fd..3f5841be 100644
--- a/docs/mcp-server.md
+++ b/docs/mcp-server.md
@@ -2,16 +2,10 @@
## Automatic HTTP setup
-The packaged GUI installs its bundled `graff` command into `~/.local/bin` on
-launch (and `~/bin` plus Homebrew/`/usr/local/bin` when those dirs are writable)
-and prepends `~/.local/bin` on zsh/bash login and interactive startup files.
-Open a new terminal if your current one was started before that PATH line.
-GUI updates refresh this managed launcher; an existing independently installed
-command is preserved. `HARNESS_NO_PATH=1` skips PATH edits.
-
-The CLI installer and first launch of the packaged GUI run `graff mcp install`.
-The GUI also offers **Tools → Configure MCP clients**. Setup requires Python 3
-(Python 3.11+ to validate Codex TOML), and macOS launchd or Linux user systemd.
+The CLI installer runs `graff mcp install`. If `graff` came with the desktop
+app, [Harness](https://github.com/justrach/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,
@@ -30,10 +24,9 @@ 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.
-The GUI runs setup once per app version after successful setup; the Tools action
-can retry or configure clients installed later.
+Run `graff mcp install` again to configure clients installed later.
-Set `GRAFF_NO_MCP=1` when installing or launching the GUI to skip automatic setup.
+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
diff --git a/docs/notices/README.md b/docs/notices/README.md
index bdff790a..1ab03476 100644
--- a/docs/notices/README.md
+++ b/docs/notices/README.md
@@ -1,10 +1,10 @@
# Notices
-Standing notes for anyone building on the desktop, including third-party ACP clients.
+Standing notes for anyone building a client on graff: the desktop app,
+[Harness](https://github.com/justrach/harness), and third-party ACP clients.
-## GUI stays 1:1 with ACP
+## Clients stay 1:1 with ACP
-Worktrees and changes to the GUI must be 1:1 with ACP (`graff acp`). A new-chat
-folder rule, a worktree handoff, or a session cwd that exists only in desktop
-chrome is not done — wire the same behavior through the ACP session in the same
+Session behavior must be 1:1 with ACP (`graff 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.
diff --git a/docs/rendered-views.md b/docs/rendered-views.md
index f0b02b46..9361017a 100644
--- a/docs/rendered-views.md
+++ b/docs/rendered-views.md
@@ -1,5 +1,7 @@
# Rendered views
+> This page describes the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/harness), which drives graff over ACP. Harness does not show rendered views yet; the page is still written to `.graff/views/` and its path is in the tool result.
+
The model can draw. When a result is easier to see than to read — a chart, a
timeline, a layout mock, a before/after — it calls **`render_html`** with one
self-contained page and the desktop app shows that page inline in the
diff --git a/docs/subagent-gui-feedback.md b/docs/subagent-gui-feedback.md
index 937b1eaa..0e36f657 100644
--- a/docs/subagent-gui-feedback.md
+++ b/docs/subagent-gui-feedback.md
@@ -1,5 +1,7 @@
# GUI child feedback integration
+> This page describes the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/harness), which drives graff over ACP. The analysis below applies to any ACP client, including Harness.
+
Status: investigated; the GUI transport below is not implemented.
## Current behavior
diff --git a/formal/acp-permissions.md b/formal/acp-permissions.md
index d3992788..72808fdd 100644
--- a/formal/acp-permissions.md
+++ b/formal/acp-permissions.md
@@ -1,5 +1,7 @@
# ACP permission ownership model
+> The desktop transport modeled here was the desktop app that used to live in this repository. The desktop app is now [Harness](https://github.com/justrach/harness); the server-side half of the model still describes `graff acp`.
+
`AcpPermissions.tla` checks the permission decision path across a server bridge and the desktop transport. The finite baseline has two worker generations. Both use the same saved session name and the same server request ID (`1`); their token atoms differ. This makes a stale desktop response meaningful even when ordinary ID and session checks would pass. The token atoms abstract unpredictable, distinct UUIDs, not their random number generator.
The model separates parsing a server request (`FrontendReceive`) from delivering it to the GUI (`GuiDeliver`), choosing a response (`FrontendRespond`), and reading that response on server stdin (`ServerAccept`). It also separates frontend cancellation (`FrontendCancel`) from server cancellation (`ServerCancel`). This allows a response to be accepted before cancel, or to be queued and rejected after cancel. `Restart` changes the active worker and clears its live token while leaving a historical GUI token available for a stale-click test. A queued wire response remains addressed to its original transport.