Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Rewrite the README around the app, for developers

dee91b25d52e84d
diff --git a/README.md b/README.md
index 969cf8775..814c04f5f 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,17 @@
https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c
-# Autonomous Harness
+# Harness
-**The way we use computers changed. The hardware didn't.**
+Harness is a desktop app for the coding agents you already run — Claude Code, Codex, Cursor, and
+eleven more — on every machine you own, in one window. Each agent is a tmux pane on the machine it
+runs on, kept there by a small daemon (`harness`). The window attaches to those panes, from this
+computer or from any other, with everything between machines encrypted end to end. An optional USB
+device puts the same agents on your desk.
-Mouse and keyboard assume your hands are on the work — you type the character, you drag the file, you
-click the button. That held for forty years. It stopped about two years ago: most of what you ship
-now, you described and an agent wrote. Your input became intent, target and judgment.
+Sessions live on the machine, not in the window. Close the laptop, open it on the train: same pane,
+same scrollback.
-Your desk never caught up. So your agents live in two tmux panes, a browser tab, and a server you
-keep forgetting about, and you alt-tab around to find the one that finished.
-
-**[Harness](https://www.autonomous.ai/harness) is the device for that.** Keyboard in the middle,
-mouse on the right, Harness on the left. Say one sentence and the work goes to whichever machine that
-agent lives on. The screen shows all of them at once.
-
-It drives the agents you already use:
+It drives the agents you already run:
<p align="center">
<img src=".github/assets/engines/claude.png" height="72" alt="Claude Code" title="Claude Code">
@@ -47,143 +43,421 @@ It drives the agents you already use:
<img src=".github/assets/engines/copilot.png" height="72" alt="GitHub Copilot" title="GitHub Copilot">
</p>
-## Add your agent to Harness
-
-Two ways to integrate. We support both **CLI** and **API**.
-
-| | **CLI** | **API** |
-|---|---|---|
-| **Your agent is** | a command you run — laptop, server, anywhere | a service on your own infrastructure |
-| **You write** | a normalizer, in TypeScript, here | an HTTP endpoint, in any language |
-| **You ship it** | as a pull request to this repo | by deploying it yourself |
-| **Start at** | [`cli/src/engines/`](cli/src/engines/README.md) | [`provider/`](provider/README.md) |
-
-To get started, run this:
+## What you get
+
+- **One window, N machines.** Panes from your laptop, the Mac mini at home and the box in the rack,
+ side by side. Create sessions, make splits, move panes, change focus, zoom, pin, pick a layout.
+- **Remote persistent sessions.** Agents run in tmux on the machine. Disconnect, reconnect, same
+ session. After a reboot the daemon recreates each pane with the engine's own `--resume` and the same
+ agent id, so the window comes back exactly as it was.
+- **No SSH, no VPN, no open ports.** Every machine dials out to the relay over a WebSocket. A terminal
+ is promoted to a direct WebRTC data channel between the two ends when ICE succeeds, and stays on the
+ relay when it doesn't. The relay holds no key material and forwards ciphertext.
+- **Remote directory lists and clone.** Start a session on another machine by browsing its filesystem
+ from the New Harness dialog, or clone a repository into a folder there first.
+- **Keyboard first.** A full default keymap, one-to-four-stroke sequences, a JSONC keymap file that
+ live-reloads, and a command palette over every action. Native macOS menus follow the same keymap.
+- **Agent-aware terminals.** Turn boundaries, the agent's own questions (`AskUserQuestion` and the
+ engines' equivalents) surfaced and answerable from the window or the device, per-turn recaps,
+ model and effort, subscription usage windows.
+- **Boss mode (⌘B).** Type or say what you want. A router picks the agent already on it from the
+ agents' names and their last recaps, and the text lands in that pane.
+- **Fourteen engines, one rule.** Harness never wraps an agent. It reads the transcript the agent
+ already writes and installs the vendor's own hooks or plugin to learn when a turn starts and ends.
+ Your credentials stay in your `~/.claude`, `~/.codex`, and so on.
+
+## Install
+
+**macOS 12+ (Apple Silicon and Intel), Linux (Ubuntu 22.04+).** Download the app from
+[harness.autonomous.ai/desktop](https://harness.autonomous.ai/desktop). On first launch it checks for
+tmux, installs a managed Node 20 and the `harness` daemon under `~/.harness`, signs you in with SSO,
+and starts the daemon. This computer is your first machine.
+
+**Add another machine** — a server, a Mac mini, a container — with the daemon alone. Node ≥ 20 and
+tmux are the prerequisites; `sqlite3` is needed only for the engines that keep their conversations in
+SQLite (OpenCode, Kilo, Hermes, Devin).
```bash
curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
-harness login
-harness start
-```
-
-`harness login` opens your browser for SSO and stores this computer's session. `harness start` refreshes
-that session when needed and connects the local adapter. There is no token to copy; the durable computer
-id keeps later starts attached to the same machine.
-
-Runs on **macOS and Linux** (Ubuntu 22.04+ verified). Node ≥ 20 and tmux are the
-prerequisites — see [`cli/README.md`](cli/README.md#supported-platforms).
-
-In the code these are named `engine` (CLI) and `provider` (API) — the folder names you'll see:
-
-```bash
-# CLI — typecheck and replay the recorded-session fixtures
-cd cli && npm install && npm run typecheck && npm test
-
-# API — run the reference implementation, then check your endpoint against it
-cd provider/reference-provider && npm install && npm run dev
-npm run conformance -- --url https://your-endpoint --key <credential>
+harness login # browser SSO, saves this computer's session
+harness start # connects; reconnects to the same machine on every later start
```
-## Harness architecture
-
-Your agents stay your processes, on your hardware, with your credentials.
+It appears in the app's machine list within a minute. There is no token to copy: a durable computer
+id under `~/.harness` keeps later starts attached to the same machine record.
+
+One thing to know from the start: **the daemon only knows about panes it created.** Sessions you start
+from the app or the web are tmux sessions named `harness-*`, owned by the daemon. A `claude` you launch
+by hand in your own tmux is not picked up.
+
+## The app
+
+### Sessions
+
+An agent is one engine process in one tmux pane on one machine. The app calls it a harness. A tab
+holds any number of panes, from any mix of machines; the app remembers tabs, pane placement, sizes,
+pinned slots, focus and zoom across restarts, in `~/.harness/desktop-app-v2/state.json`.
+
+**New Harness (⌘N)** asks for four things: the machine, the working folder, the engine, and,
+under Advanced, two settings most people never touch. The folder picker is the native panel on this
+computer and a remote directory list on any other machine, served over the daemon's `fs_list_dir`.
+**Clone repository** clones a GitHub URL into a parent folder first. The engine row shows every engine
+the machine has, probes availability live, and marks the ones the daemon would install on first
+launch. Advanced holds the engine's permission-bypass flag (`--dangerously-skip-permissions`,
+`--dangerously-bypass-approvals-and-sandbox`, `--force`, `--auto`, whichever the engine has) and,
+for Codex, a profile: a `CODEX_HOME` folder to launch under instead of `~/.codex`, each with its own
+hooks.
+
+Creation carries a receipt. If the reply is lost, the button turns into **Check status** rather than
+creating a second session.
+
+Closing a pane is a view operation; the agent keeps running. **Stop Harness** ends the engine process
+and asks first. **Restart Harness** relaunches it in the same pane with the same id, resuming the
+conversation where the engine supports it.
+
+**Open Harness (⌘O)** is the search: agents, tabs, projects, machines, history and commands, fuzzy
+matched, with a session preview on the right built from cached recent turns. Type `>` for commands
+only (also ⇧⌘P).
+
+### Panes and layouts
+
+Hover the right or bottom edge of a pane for a split control, or ⌘R and ⌘D to split right and down;
+both open the same picker at that position. Drag a pane's header onto another pane to swap them.
+Resize grips live in the gaps and appear on hover or keyboard focus; sizes are remembered per pane
+count.
+
+**Layout (⌘S)** opens a palette of drawn shapes rather than names: Split, Columns, Rows, Main
+left/right/top/bottom, Grid, 2 to 5 columns, Middle + sides, Two over three, Auto. Press ⌘S again to
+cycle, a digit to pick directly, Enter to apply. A pinned pane keeps its slot when other panes close
+around it.
+
+### Keyboard
+
+The defaults, in the workspace:
+
+| Keys | Action |
+|---|---|
+| ⌘N | New Harness |
+| ⌘O | Open Harness — search sessions, tabs, machines, history; `>` for commands |
+| ⇧⌘P | Command palette |
+| ⌘B | Boss mode: describe a task, it picks the agent |
+| ⌘T · ⌘W · ⇧⌘T · ⇧⌘R | New tab · close tab · reopen last closed · rename tab |
+| ⌘1 … ⌘9 | Select tab by position |
+| ⇧⌘] · ⇧⌘[ · ⌃Tab · ⌃⇧Tab | Next · previous tab |
+| ⌘] · ⌘[ · ⌘Y | Forward · back through visited harnesses · full history |
+| ⌘H ⌘J ⌘K ⌘L · ⌘arrows | Focus the pane left · below · above · right |
+| ⇧⌘arrows | Move the focused pane |
+| ⌘R · ⌘D | Split right · split down |
+| ⌘⏎ · ⌘; · ⇧⌘W | Zoom or restore · last pane · close pane |
+| ⌘S | Layout palette |
+| ⌘F · ⌘G · ⇧⌘G | Find in terminal · next · previous match |
+| ⇧⌘I | Harnesses needing input |
+| ⌘, · ⌘/ | Settings · keyboard shortcuts |
+
+In a picker: ↓ ⌃N ⌃J and ↑ ⌃P ⌃K move, ⏎ opens, ⌘⏎ adds the result as a pane here, Esc or ⌃G closes.
+The terminal keeps ⌘C, ⌘V, ⌘A, Esc, ⌥⏎ and ⌃C for itself. `pane.pin`, `pane.focus_1…9`,
+`pane.resize`, `pane.reset_sizes`, `machine.link` and a few others ship unbound and are in the palette.
+
+Remap anything in `~/.config/harness/keybindings.jsonc` (`$XDG_CONFIG_HOME` respected). The file is
+JSONC: `{ "version": 1, "bindings": [{ "keys": "cmd+k cmd+l", "command": "pane.focus_right",
+"when": "workspace" }] }`. Sequences are one to four strokes; `"command": null` unbinds a key or a
+whole prefix; `when` is `workspace`, `terminal` or `picker`. The file is watched and reloaded on save;
+a bad edit keeps the last good keymap and says what was wrong. **Keyboard shortcuts (⌘/)** lists the
+effective bindings and **Open keyboard config** writes a commented template with every command id.
+
+### Terminal
+
+The renderer is a vendored, patched [xterm](desktop/third_party/xterm). Each pane has its own find bar
+(⌘F). ⌘-click opens links; an image or video path in the output opens in a preview, downloaded from
+the remote machine over the existing encrypted connection with progress and cancel (up to 512 MiB).
+Paste or drop an image onto a pane to send it to the agent. On a remote machine a composer box under
+the pane batches a message instead of paying a round trip per keystroke. Scrollback is restored from
+the daemon's snapshots on attach, resize, zoom and reconnect. Font, size (⌘0, ⌘+, ⌘-), terminal
+colours and six app palettes are in Settings.
+
+### Attention, models, usage
+
+When an agent asks a question the pane gets an amber ring, the titlebar bell lights, and ⇧⌘I lists
+every harness waiting on you. Answers go back into the engine's own dialog; there is no side channel.
+
+The **Models** menu shows each engine's subscription usage window, refreshed once a minute, for local
+and remote machines alike. Settings ▸ Usage is a separate token ledger read from Claude's and Codex's
+transcripts and OpenCode's database, off per provider until you switch it on.
+
+### Machines
+
+The app talks to the daemon on this computer over a loopback socket and never dials the relay itself.
+Other machines are reached through that daemon: it links to them with a per-machine remote password,
+terminates the encryption locally, and hands the app plaintext. Machines ▸ Link Machine… runs the
+link flow; the CLI equivalent is under [The daemon and CLI](#the-daemon-and-cli).
+
+## How it works
```
- ( ◉ ) Harness
+ ( ◉ ) Harness device (USB)
│
+ ┌─────────── this computer ───────────┐
+ │ Harness app ── loopback ──▶ harness daemon ──▶ tmux ──▶ claude · codex · … │
+ └──────────────────────────────┬──────┘
+ │ WebSocket (E2EE)
╔═════════╧═════════╗
- ║ Harness Relay ║ end-to-end encrypted
+ ║ Harness Relay ║ store and forward, no keys
╚═════════╤═════════╝
┌───────────────────────┼───────────────────────┐
- │ │ │
- your laptop your server your platform
- `harness login` + `harness login` + your HTTP API
- `harness start` `harness start`
- │ │ │
- claude · codex hermes · muse agents running on
- cursor · amp · … opencode · kilo · your own servers
- grok · agy · copilot
-
- └───────── CLI ─────────┘ └─────── API ───────┘
+ your server your platform harness.autonomous.ai
+ harness daemon your HTTP API the web client
+ tmux · hermes · muse (provider) (paired browser)
+ ▲
+ └── terminal traffic goes direct over WebRTC when ICE succeeds
```
-This repo holds all three sides of that picture: the CLI in [`cli/`](cli/README.md), the relay
-backend in [`backend/`](backend/README.md), and the desktop app that attaches terminals to your
-machines in [`desktop/`](desktop/README.md). Each releases on its own tag — see
-[`docs/cicd.md`](docs/cicd.md).
+**The daemon** runs detached under your account. Every five seconds it reconciles the `harness-*`
+tmux sessions with its registry; a pane has to be missing on two scans before its agent is marked
+gone. It tails each agent's transcript with a byte offset (JSONL for most engines, SQLite for
+OpenCode, Kilo, Hermes and Devin) and turns lines into a normalized event stream: turn started,
+tool call, sub-agent, question, turn ended. Hooks it installs into the vendor CLI tell it about
+session start, prompt submit and stop. Every five minutes it re-reads engine configs and pane
+footers to keep model and effort right. On start it restores panes that died with the tmux server,
+and it self-updates from a signed manifest, swapping the bundle atomically.
-There is a fourth side, and it is a physical one: [`device/esp32-circle/`](device/esp32-circle/README.md)
-is the firmware for the Harness dial, a round 466×466 AMOLED you plug into a USB port. It is not
-another client of the backend — since August 2026 it holds no credential and speaks no WiFi, and is
-served entirely over the cable by the `harness` daemon on the computer it is plugged into
-([`docs/specs/cable-protocol.md`](docs/specs/cable-protocol.md)). It ships over the air rather than on
-a tag: `make upload-circle`.
+**The session model.** The registry (`~/.harness/cli/data/registry.json`, mode 0600) is the source of
+truth for agents: engine, working directory, tmux pane, bound transcript, process identity. Layouts
+belong to the app. The relay stores machine records, agent names and daily counters, never a
+transcript, a recap or a keystroke.
-## End-to-end encryption
-
-On the CLI path it's always on — there's no switch for it. Everything between your machines and the
-device is ciphertext by the time it reaches us.
+**Transport.** Each daemon holds one WebSocket to the relay, authenticated with its SSO token.
+Terminal bytes ride a binary channel on that socket until a WebRTC data channel negotiates, then move
+to it. Encryption is on for every path and has no switch:
- **Ed25519** identity keys, pinned at first pairing and signing every ephemeral after it.
-- A **CPace-style PAKE** over ristretto255 — the six-character pairing code bootstraps a shared
- secret across the untrusted relay, and an attacker gets **one online guess**. There's no offline
- attack on it.
+- A **CPace-style PAKE** over ristretto255 — the six-character pairing code bootstraps a shared secret
+ across the untrusted relay, and an attacker gets one online guess.
- **X25519** ephemeral Diffie–Hellman per connection, through HKDF to pairwise session keys.
-- A **per-process group key** so one event encrypts once for many readers, carrying its own epoch id.
-- **ChaCha20-Poly1305** on every frame, with the associated data binding the frame's type and
- session, so a frame can't be replayed into a context it wasn't written for.
-
-Harness Relay stores and forwards. It holds no key material, so it can't read a prompt, a diff, a
-result, or the name of what you're working on.
+- A **per-process group key** so one event encrypts once for many readers.
+- **ChaCha20-Poly1305** on every frame, with the associated data binding frame type and session.
+
+The crypto core lives in [`cli/src/lib/e2ee/`](cli/src/lib/e2ee/) and is a byte-identical twin of the
+browser's copy, with a drift-guard test and committed self-vectors.
+
+## The daemon and CLI
+
+`harness` is one pure-JS bundle run by the managed Node under `~/.harness/cli`. Everything below
+works the same on a headless Linux server; the app is not required on a machine, only the daemon.
+
+| Command | What it does |
+|---|---|
+| `harness login [--force] [--json]` | Browser SSO; save this computer's session. `--force` signs in as a different account. `--json` emits NDJSON for GUI clients. |
+| `harness start [-f] [--repair]` | Start the daemon from the saved session. `-f` runs in the foreground for a supervisor. `--repair` re-verifies the managed Node runtime. |
+| `harness stop` · `harness logout` · `harness reset` | Stop the daemon · stop and clear the SSO session · stop and clear all local state. |
+| `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. |
+| `harness machines [list] [--json]` · `harness machines delete <id>` | This account's machines · remove another machine (never this one). |
+| `harness pair <code>` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. |
+| `harness browser-link` | Print a reusable seven-day setup link for browsers. |
+| `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. |
+| `harness link connect <id> [--name=<label>]` · `harness link list` · `harness link unlink <id>` | Let this machine reach another of yours, terminating E2EE here; list; unlink. |
+| `harness grid login [--force] [--json]` · `harness grid logout` | Sign the `grid` CLI in with this computer's account, no second browser. |
+| `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. |
+| `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |
+
+Interactive prompts read one line from stdin with `--stdin`; `--json` switches any of them to NDJSON.
+
+The daemon also serves a loopback dashboard at `http://127.0.0.1:18473`: health, this machine's
+fingerprint, paired clients, stop. It never renders a transcript. Configuration is environment
+variables (`BACKEND_WS_URL`, `WEB_URL`, `ADAPTER_DATA_DIR`, `ADAPTER_COMPUTER_ID`, `PORT`, and the
+per-engine home directories); [`cli/README.md`](cli/README.md) has the full table and the
+`.env.example`.
+
+## Automation
+
+The app is one client of the daemon. Anything on the same computer can be another: the loopback
+WebSocket at `ws://127.0.0.1:18473/api/local-ws` takes a `machine_select` frame first
+(`{ machineId, localProtocolVersion: 1 }`, no `Origin` header), then request frames with a `requestId`
+and answers them with `<type>_result`. Selecting one of your other machines proxies the request
+through this daemon's link to it.
+
+What it answers: `agents_list`, `agent_create`, `agent_restart`, `agent_retarget`, `agent_delete`,
+`agent_update`, `agent_recent`, `agent_files`, `agent_read_file` (text, or media in 128 KiB chunks),
+`fs_list_dir`, `engines_probe`, `codex_profiles_list`, `codex_profile_link`, `models_list`,
+`usage_read`, `question_response`, `voice_route`, `message`, `cancel`, and `terminal_open` for a
+binary terminal channel with scroll, resync and paste. The same frames travel from the web client
+over the relay.
+
+Engines report in over HTTP on the same port: `POST /api/hook/session-start`, `session-end`,
+`turn-start`, `turn-stop`, `tool-start`, authenticated by a per-install token the daemon writes into
+the hook it installs.
+
+There is no `harness new` or `harness split` today. Sessions are created and arranged through the app,
+the web client, or this socket.
+
+## Engines
+
+| Engine | Binary | How Harness follows it | Resume | Permission bypass | Grid |
+|---|---|---|---|---|---|
+| Claude Code | `claude` | hooks in `~/.claude/settings.json` + JSONL transcript | `--resume` | `--dangerously-skip-permissions` | yes |
+| Codex | `codex` | `hooks.json` per `CODEX_HOME` + JSONL rollouts | `resume` | `--dangerously-bypass-approvals-and-sandbox` | yes |
+| Cursor | `cursor-agent` | `~/.cursor/hooks.json` + transcript | `--resume` | `--force` | — |
+| OpenCode | `opencode` | plugin + SQLite | `--session` | `--auto` | yes |
+| Pi | `pi` | extension + transcript | `--session` | — | yes |
+| Hermes | `hermes` | hooks + SQLite | `--resume` | — | yes |
+| Command Code | `cmd` | hooks + transcript | `--resume` | — | — |
+| Devin | `devin` | hooks + SQLite | — | — | — |
+| Muse Code | `muse` | transcript | `resume` | — | — |
+| Amp | `amp` | plugin writes the transcript Harness tails | `threads continue` | — | — |
+| Kilo | `kilo` | plugin + SQLite | `--session` | — | — |
+| Grok Build | `grok` | hooks + `updates.jsonl` | `--resume` | — | yes |
+| Antigravity | `agy` | hooks + transcript | `--conversation` | — | — |
+| GitHub Copilot | `copilot` | hooks + transcript | `--resume` | — | yes |
+
+A launcher that hands the pane to one of these is that engine: `ori claude` is a Claude Code agent,
+and the daemon reads the gateway off the live process so recaps and routing go through it too.
+
+**Grids.** An agent can be pointed at an [Autonomous Grid](https://www.autonomous.ai/grid) relay
+instead of the engine's own login, at creation or later with **Retarget**, which respawns the same
+pane with the grid's environment and `--resume`. The engines marked above support it; the key travels
+in the tmux session environment, never in argv or a file. Needs tmux ≥ 3.2.
+
+## The Harness device
+
+A round 466×466 AMOLED with touch and a far-field microphone, USB-C on the bottom edge. It has no
+WiFi and holds no credential. It is served entirely over the cable by the daemon on the computer it is
+plugged into; plugging it in is the authorization. The wire is one USB serial device (`303a:1001`),
+framed as `A5 5A | ver | type | len | payload | crc16` with a JSON vocabulary, a five-second ping,
+and a hard 8 KiB frame ceiling, specified in [`docs/specs/cable-protocol.md`](docs/specs/cable-protocol.md).
+
+What it shows: your agents as tiles in the order of the window's panes, with what each is doing and
+for how long; a wheel of your machines; the agent's own question when it asks one, answerable with a
+tap; the recap when a turn finishes, with one quiet tone. Scroll the face to scroll the terminal.
+Double-tap and speak to send a task: the audio goes to the daemon as PCM, comes back as a transcript,
+and Boss mode routes it. A voice turn can carry a mode — `/goal` runs an instruction to done,
+`/loop` on a schedule — adapted per engine; `/loop` is Claude Code only today.
+
+Firmware updates travel over the same cable in 16 KB credit windows, offered from the published
+metadata and never for a dev build. `harness flash` re-flashes a device from a USB port. The firmware
+is ESP-IDF ≥ 5.5 under [`device/esp32-circle/`](device/esp32-circle/) (`idf.py set-target esp32s3 &&
+idf.py build`); `make device-test` runs the host-side tests with no board attached.
+
+## Extend Harness
+
+### Add your agent
+
+Two paths. Both are first-class and both are in this repo.
+
+| | **CLI engine** | **API provider** |
+|---|---|---|
+| Your agent is | a command you run, anywhere `harness login` runs | a service on your own infrastructure |
+| You write | a normalizer in TypeScript, here | an HTTP endpoint, in any language |
+| You ship it | as a pull request to this repo | by deploying it yourself |
+| Start at | [`cli/src/engines/README.md`](cli/src/engines/README.md) | [`provider/`](provider/README.md) |
-The crypto core is a byte-identical twin of the browser's copy, with a drift-guard test that fails if
-the two ever diverge, and committed self-vectors that catch a crypto library changing underneath it.
-The code is in [`cli/src/lib/e2ee/`](cli/src/lib/e2ee/).
+A CLI engine touches about twenty shared files, and the engines README is that list in dependency
+order. The one rule: every field name, event kind and tool name comes from a real recorded session of
+the real binary, never inferred from another engine. If your agent writes nothing to disk, look at Amp:
+its plugin writes the transcript, and from there it is an ordinary engine.
-## How to contribute
+```bash
+cd cli && npm install && npm run typecheck && npm test # replay the recorded-session fixtures
+```
-Harness welcomes two kinds of CLI integration. Open an issue before writing code so we can confirm
-the integration shape and the real software a maintainer will need to reproduce it. The complete
-review and pull-request workflow is in [CONTRIBUTING.md](CONTRIBUTING.md).
+An API provider implements eight JSON-RPC 2.0 methods over HTTPS with SSE for the one that streams:
+`agent.list`, `agent.send`, `agent.history`, `turn.cancel`, `agent.create`, `agent.rename`,
+`agent.delete`, `agent.recap`. No SDK, no discovery, no capability negotiation. The reference
+implementation ships the conformance runner; zero failures is the bar.
-### 1. Add an agent framework
+```bash
+cd provider/reference-provider && npm install && npm run dev # http://127.0.0.1:4319
+npm run conformance -- --url https://your-endpoint --key <credential>
+```
-To add an agent CLI such as Claude Code or Grok, start by recording a real session from the real
-binary. The recording is the source of truth for transcript fields, event names, tools, turn
-boundaries, model metadata and capabilities — do not infer them from another engine.
+### Add a terminal multiplexer
-An engine contribution covers process detection, session discovery, transcript reading and event
-normalization, prompt/control behavior, product surfaces, and replay fixtures. Follow
-[`cli/src/engines/README.md`](cli/src/engines/README.md) for the dependency-ordered checklist, then
-run:
+Harness watches tmux with nothing to configure. A second multiplexer is added beside tmux, not in
+place of it. Before writing code, confirm two things: a process inside a pane can identify that pane
+with a stable, multiplexer-namespaced id, and your tool's presence is detectable without running it,
+so a machine that lacks it pays nothing. Then implement: list panes with PID and working directory,
+send literal text and keys, capture a pane, display a message, create and kill sessions. Carry the new
+pane identity through process discovery, registry persistence and hooks, and scrub it from recap
+workers so they cannot register as phantom agents. The retired Herdr backend is still in the tree
+(`cli/src/lib/herdrBackend.ts`) as the worked example of the contract; see
+[Adding a multiplexer](CONTRIBUTING.md#adding-a-multiplexer).
```bash
-cd cli && npm install && npm run typecheck && npm test
+cd cli && npm run test:tmux-real # the real multiplexer discovery suite
```
-### 2. Add a terminal multiplexer
+### Add a domain harness
+
+Circuit (PCB design) and Workshop (3D CAD) are being packaged as domain harnesses: a git repo with a
+manifest, the domain's skills, a workspace template, a verifier that writes one verdict file, and an
+optional viewer that opens in a pane beside the terminal, installed with `harness dsh install`. The
+work is on the `dsh-mvp` branch and this section lands with it.
+
+## Providers, relay, web
-Harness watches tmux, with nothing to configure: `tmux new` then an engine produces an agent. (Herdr
-was supported and has been retired — the backend contract it was written against is still in the tree,
-so it remains the worked example of what a second multiplexer has to implement.)
-Another multiplexer must be added alongside tmux, not replace it. Before coding, confirm that a
-process inside a pane can identify that pane with a stable, multiplexer-namespaced id — and that your
-tool's presence can be detected without running it, since a machine that does not have it must pay
-nothing. The integration must support listing panes with their PID and working directory, sending
-literal text and keys, capturing pane output, displaying a message, and creating and killing sessions.
+- **`provider/`** — the spec ([`spec/README.md`](provider/spec/README.md)), the deterministic
+ [`reference-provider`](provider/reference-provider/) with the conformance runner on port 4319, and
+ [`example-provider`](provider/example-provider/), a real one backed by the local `claude` CLI on
+ port 4502 (read its README before running it; it skips permissions). `provider/e2e` runs both.
+- **`backend/`** — the relay: Node, MongoDB via Prisma, Redis. It terminates four WebSocket paths
+ (`/api/adapter-ws` for daemons, `/api/web-ws`, `/api/device-ws`, `/api/manager-ws`), signals WebRTC
+ and hands out STUN/TURN, and persists machines, agent names and counters. `npm install && npm run
+ dev` on `:8085`; [`backend/README.md`](backend/README.md) and `.env.example` for the rest.
+ `harness-api.autonomous.ai` is the hosted instance.
+- **The web client** at [harness.autonomous.ai](https://harness.autonomous.ai) reaches the same
+ machines from a browser after `harness pair <code>` or a `harness browser-link`. It is not in this
+ repository; it also hosts the CLI installer and the desktop downloads.
-The contribution must also carry the new pane identity through process discovery, registry
-persistence and hooks, and scrub it from recap workers so they cannot register as phantom agents.
-See [Adding a multiplexer](CONTRIBUTING.md#adding-a-multiplexer) for the compatibility requirements,
-then run the normal CLI checks plus the real multiplexer discovery suite:
+## Repository layout
+
+```
+desktop/ the app (Flutter; macOS and Linux). third_party/xterm is the patched terminal core
+cli/ the harness daemon and CLI (TypeScript, one bundle). src/engines/ is one folder per engine
+backend/ the relay (Node, Prisma/MongoDB, Redis)
+provider/ the API-provider spec, reference and example providers, conformance runner
+device/ firmware for the Harness device (ESP-IDF, esp32-circle)
+docs/ specs (the cable protocol), design notes, plans, release map (cicd.md)
+```
+
+## Development
```bash
+# cli
cd cli && npm install && npm run typecheck && npm test
-npm run test:tmux-real
-npm run test:herdr-real
-```
+make install-cli # bundle this tree into ~/.harness/cli and restart the daemon on it
-## Security and licence
+# desktop (Flutter ≥ 3.47 / Dart ≥ 3.13; SPM on for macOS)
+cd desktop && flutter pub get && flutter analyze && flutter test
+flutter run -d macos # or -d linux
+
+# backend
+cd backend && npm install && npm run typecheck && npm test
+
+# provider
+cd provider/e2e && npm install && npm test
+
+# device
+make device-test
+```
-- Security reports go to [SECURITY.md](SECURITY.md) rather than the issue tracker.
-- [MIT](LICENSE).
+Each product releases on its own tag and the suffix routes the workflow: `vX.Y.Z_cli` bundles and
+publishes the daemon (running daemons pick it up within a minute), `vX.Y.Z_backend` builds the image,
+`vX.Y.Z_desktop` builds, signs and publishes both macOS bundles and both Linux architectures.
+`make release-cli|release-backend|release-desktop` cut them; `make upload-circle` publishes device
+firmware over the air. `ci.yml` runs the CLI suite on every pull request and holds no secrets, which
+is what lets it run on a fork's code; see [`docs/cicd.md`](docs/cicd.md). `make remote-machine`
+brings up a second machine in Docker so the remote path can be exercised from one laptop.
+
+## Docs
+
+- [`docs/specs/cable-protocol.md`](docs/specs/cable-protocol.md) — the device wire, the only thing the firmware and the daemon share.
+- [`docs/cicd.md`](docs/cicd.md) — workflows, tags, credentials, dry runs.
+- [`docs/harness-v2-handoff.md`](docs/harness-v2-handoff.md) — the current state of the app, superseding the other `harness-v2-*` notes; [`docs/harness-v2-keyboard-system.md`](docs/harness-v2-keyboard-system.md) for the keymap design.
+- [`docs/harness-agent-creation.md`](docs/harness-agent-creation.md), [`docs/harness-agent-lifecycle.md`](docs/harness-agent-lifecycle.md), [`docs/harness-agent-first-tabs.md`](docs/harness-agent-first-tabs.md) — how sessions are created, kept and shown.
+- [`docs/autonomous-device-integration.md`](docs/autonomous-device-integration.md) — direct LAN pairing with Autonomous OS devices.
+- [`cli/README.md`](cli/README.md), [`desktop/README.md`](desktop/README.md), [`backend/README.md`](backend/README.md), [`provider/README.md`](provider/README.md) — per-package detail.
+
+## Contributing, security, licence
+
+Open an issue before writing an engine or a multiplexer so the integration shape and the real software
+a maintainer needs to reproduce it are agreed first; the review and pull-request workflow is in
+[CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to [SECURITY.md](SECURITY.md), not the issue
+tracker. [MIT](LICENSE).