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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
README: short, the selling points first, the detail in docs/
dee0ddcad74727e
diff --git a/.github/assets/screenshots/marp.png b/.github/assets/screenshots/marp.pngnew file mode 100644index 000000000..c8af4d576Binary files /dev/null and b/.github/assets/screenshots/marp.png differdiff --git a/.github/assets/screenshots/new-agent.png b/.github/assets/screenshots/new-agent.pngnew file mode 100644index 000000000..e67d539bdBinary files /dev/null and b/.github/assets/screenshots/new-agent.png differdiff --git a/.github/assets/screenshots/solid.png b/.github/assets/screenshots/solid.pngnew file mode 100644index 000000000..51c05ce30Binary files /dev/null and b/.github/assets/screenshots/solid.png differdiff --git a/README.md b/README.mdindex a0011e638..42323674a 100644--- a/README.md+++ b/README.md@@ -2,10 +2,33 @@ https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c# Harness-Harness is a desktop app for agents that build things. Code, with Claude Code, Codex, Cursor and-eleven more. PCBs, with Copper. 3D parts, with Solid. Keynotes, with Marp. One window, every machine-you own. Each agent is a persistent terminal on the machine it runs on, and for the domains beyond-code, a viewer beside it shows the work as it is made.+Agents that build things, in one window. Code with Claude Code, Codex, Cursor and eleven more. PCBs+with Copper. 3D parts with Solid. Keynotes with Marp. Every agent runs in a persistent terminal on+any machine you own, and the domains beyond code get a viewer beside it that shows the work as it+is made.++<p align="center">+ <img src=".github/assets/screenshots/marp.png" width="960" alt="A Marp tab: the keynote in the viewer on the left, the Claude Code agent that wrote it on the right, ten slides and Ready in the header">+</p>++## Why Harness++- **More than code.** Copper (PCB), Solid (3D design) and Marp (Slides) sit beside the coding+ agents. One prompt, and the pane fills with the board, the part, the keynote while the agent works.+- **Your agents, unwrapped.** Fourteen engines. Harness reads the transcript each one already writes+ and installs the vendor's own hooks; it never wraps a CLI. Credentials stay in your `~/.claude`,+ `~/.codex`, and so on.+- **Sessions that outlive the laptop.** Every agent is a tmux pane on its machine, kept by a small+ daemon. Close the lid, open it on the train: same pane, same scrollback. After a reboot the daemon+ brings each one back with the engine's own `--resume`.+- **Every machine, no SSH.** Laptop, the Mac mini at home, the box in the rack, side by side. Each+ machine dials out; nothing to open; encrypted end to end through a relay that holds no keys.+- **Built for the keyboard.** ⌘N for a new agent, ⌘O to find anything, ⌘B to say what you want and+ have it land on the right agent. Every key remappable in one file.+- **A device for the desk.** A round USB display with your agents as tiles, their questions+ answerable with a tap, and a voice turn a double-tap away.++## Harnesses| Harness | You say | You get | You watch ||---|---|---|---|@@ -13,18 +36,19 @@ code, a viewer beside it shows the work as it is made.| **Copper** · PCB | "a USB-C powered ESP32 sensor board" | a fab-ready board, ordered in a click | the board, its checks, the fab || **Solid** · 3D design | "an iPhone case with a lanyard loop" | a printable STEP part | the model: Build, Fit, Print, Review || **Marp** · Slides | "a launch keynote for 200 engineers" | a keynote with art and speaker notes | the slides filling in, then Present |-| **Yours** | | anything an agent can build in a folder | [add a domain harness](#add-a-domain-harness) |+| **Yours** | | anything an agent can build in a folder | [build a harness](#extend-harness) |-Every harness is the same thing to the app: a tile in New Agent, and a tab with the agent's terminal-on the right, the domain's viewer on the left, and the pane header saying where the work is. The-domain lives in its own git repository, installed on first use, never in Harness itself.+<p align="center">+ <img src=".github/assets/screenshots/solid.png" width="960" alt="A Solid tab: the 3D part in the viewer, the Codex agent that made it beside it, Ready in the header">+</p>-Each terminal 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. Close the laptop, open it on the train: same pane, same scrollback.-An optional USB device puts the same agents on your desk.+Every harness is the same thing to the app: a tile in New Agent, a tab with the terminal on the+right and the domain's viewer on the left, and a header that says where the work is. The domain+lives in its own git repository, installed on first use, never in Harness itself.-It drives the agents you already run:+<p align="center">+ <img src=".github/assets/screenshots/new-agent.png" width="720" alt="New Agent: choose a harness — Codex, Claude Code, OpenCode, and under More: Copper PCB, Solid 3D design, Marp Slides, Cursor, Pi, Hermes…">+</p><p align="center"><img src=".github/assets/engines/claude.png" height="72" alt="Claude Code" title="Claude Code">@@ -66,33 +90,6 @@ And the harnesses for the domains beyond code, each on one of those agents:<img src=".github/assets/engines/marp.png" height="72" alt="Marp · Slides" title="Marp · Slides, on Claude Code"></p>-## What you get--- **Harnesses for more than code.** Copper (PCB), Solid (3D design) and Marp (Slides) sit beside the- coding agents in New Agent. Pick one and the tab opens with the domain's viewer next to the- terminal, the domain's skills in the agent, and its toolchain installed on the machine. Build your- own from the starter in an afternoon: [Add a domain harness](#add-a-domain-harness).-- **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 Agent 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@@ -117,489 +114,64 @@ One thing to know from the start: **the daemon only knows about panes it createdfrom the app or the web are tmux sessions named `harness-*`, owned by the daemon. A `claude` you launchby 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 device (USB)- │- ┌─────────── this computer ───────────┐- │ Harness app ── loopback ──▶ harness daemon ──▶ tmux ──▶ claude · codex · … │- └──────────────────────────────┬──────┘- │ WebSocket (E2EE)- ╔═════════╧═════════╗- ║ Harness Relay ║ store and forward, no keys- ╚═════════╤═════════╝- ┌───────────────────────┼───────────────────────┐- 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-```+## First five minutes-**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.--**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.--**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.-- **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.-- **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.+**⌘N** New Agent: a harness, a machine, a folder, Create. **⌘O** finds any agent, tab, project or+machine, and `>` runs a command. **⌘B** takes a task in plain words and routes it to the agent+already on it. **⌘R** and **⌘D** split, **⌘S** picks a layout, **⌘⏎** zooms a pane, **⇧⌘I** lists+the agents waiting on you. The full keymap, and how to remap it: [docs/keyboard.md](docs/keyboard.md).+The window in detail: [docs/app.md](docs/app.md).## Extend Harness-### Add your agent+Every layer has a contract, a starter and a check.-Two paths. Both are first-class and both are in this repo.--| | **CLI engine** | **API provider** |+| Add | Start at | The bar ||---|---|---|-| 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) |--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.--```bash-cd cli && npm install && npm run typecheck && npm test # replay the recorded-session fixtures-```--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.--```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>-```--### Add a terminal multiplexer--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 run test:tmux-real # the real multiplexer discovery suite-```--### Add a domain harness--A domain harness turns Harness into a product for one domain. Copper makes PCBs, Solid makes 3D-parts, Marp makes keynotes; yours can make anything an agent can build in a folder. To the user it-is one more tile in New Agent, with a category under the name. Pick it and you get a tab of its own:-the domain's viewer on the left, the engine's terminal on the right, the engine started with the-domain's skills in a workspace the harness laid out, and the pane header reporting where the work is.--Nothing about the domain lives in this repo. A harness is a git repository that Harness installs on-a machine on first use. Harness reads one manifest, copies files into the workspace, runs the commands-the manifest names, and watches one JSON file. That is the whole coupling.--| In the repo | What it is |-|---|---|-| `harness.json` | the manifest: id, name, category, base engine, workspace, skills, toolchain, viewer, verdict path |-| `AGENTS.md` | what the engine is told in every workspace; a `claude` base gets a `CLAUDE.md` that imports it |-| `skills/` | the domain's craft as `SKILL.md` bundles, symlinked into the workspace so edits are live |-| `template/` | a fresh workspace, copied once into an empty folder, plus an optional `init` script |-| `toolchain/setup`, `doctor` | install the domain's tools at install time; say what is missing, one line per check |-| `viewer` | a loopback web server Harness runs beside the terminal; the pane is a webview on it |-| `.harness/verdict.json` | the one file the domain writes and Harness reads: ready or not, findings, phases |--#### Build one--1. **Copy the starter.** [`dsh/starter-dsh/`](dsh/starter-dsh/) is a complete tier-0 harness: a- manifest, an `AGENTS.md`, one skill, a template, a toolchain that installs nothing.-- ```bash- cp -r dsh/starter-dsh ~/code/my-harness && cd ~/code/my-harness && git init- ```-- In `harness.json` set `id` (`owner/name`, the install directory and the wire id), `name` (the- tile), `category` (the tile's second line), `engine` (`claude` or `codex`), and- `workspace.marker` (a file whose presence means the workspace is already laid out).--2. **Tell the agent its job.** `AGENTS.md` says what the workspace is, where things go, what to do- first, and how to work so the pane moves: first save within a minute, then build up, check after- every pass. The craft itself goes in `skills/<name>/SKILL.md`: the dialect, the patterns, the- commands. Skills are symlinked, so a change in your checkout is live in every workspace.--3. **Lay out the workspace.** `template/` is copied into an empty folder once; then- `workspace.init` runs with the workspace as its working directory and `HARNESS_DSH_DIR` pointing- at the install. Seed the first verdict here so the header has a state before the first prompt.--4. **Ship the toolchain with the harness.** `toolchain/setup.sh` runs once at install, in the- install directory: pin versions and vendor them there (a `node_modules`, a `.venv`), never into- the user's machine. `toolchain/doctor.sh` exits 0 when the machine can run the harness and prints- one line per check; Harness shows those lines. Point the agent at the tools through `agent.env`- (`"MARP_TOOLCHAIN": "${dsh}/toolchain"`); `${dsh}`, `${workspace}` and `${home}` expand.--5. **Write the verdict as a feed.** `.harness/verdict.json` is written at every check and every- phase change, not at the end. `ready` is the one machine truth; `summary` is the header's line;- `phases` is how the header says "you are here".-- ```json- { "spec": 1, "ready": false, "summary": "10 slides so far · 1 warning",- "findings": [{ "severity": "warning", "kind": "dense", "message": "slide 4 has 61 words" }],- "artifact": "deck.md",- "phases": [{ "id": "outline", "name": "Outline", "state": "done" },- { "id": "draft", "name": "Draft", "state": "active" },- { "id": "polish", "name": "Polish", "state": "pending" }],- "updatedAt": "2026-09-15T23:33:00Z" }- ```--6. **Add the viewer.** `viewer.command` is a long-running process. Harness starts it with- `HARNESS_VIEWER_PORT`, `HARNESS_WORKSPACE`, `HARNESS_DSH_DIR` and `HARNESS_DSH` in its- environment, waits for the port to open on `127.0.0.1`, then loads `viewer.url` in the pane- (`${port}` and `${artifact}` expand; the artifact is what the verdict names, or the newest file- matching `artifactExtensions`). Serve files from the workspace and nothing outside it, watch the- workspace, push a reload on every change, and re-run your check on every change so the header- moves while the agent writes without the agent running anything. Marp's viewer does all of this- in about 110 lines of Node with no dependencies beyond its renderer.--7. **Check it, install it, run it.**-- ```bash- harness dsh check . # conformance: the manifest, the scripts, the schemas- harness dsh install . --link # this checkout as the installed harness (a symlink)- harness dsh doctor owner/name # what the machine is missing, if anything- harness dsh list # installed here, and what the registry offers- ```-- Then New Agent, your tile, a folder, a prompt. For a check without the app,- [`dsh/tools/dsh-e2e.mjs`](dsh/tools/) creates an agent over the daemon's loopback socket and- reports the materialized workspace, the viewer URL, the pane's environment and the first verdict.- The viewer process reads its own files when it starts; after you edit it, kill it and the daemon- respawns it on the new code.--8. **Publish.** Add `dsh/registry/<owner>/<name>.json` in a pull request:-- ```json- { "id": "owner/name", "name": "Name", "category": "Thing", "description": "One line.",- "repo": "https://github.com/owner/name", "ref": "main", "engine": "claude",- "tier": 2, "verified": false }- ```-- CI clones the repo at that ref and runs the conformance check. Once merged, the app offers the- tile before the harness is installed and installs it on Create; `verified: true` is for- first-party entries, everything else shows its git URL on install.--#### Tiers--| Tier | Ships | Harness shows |-|---|---|---|-| 0 | manifest, `AGENTS.md`, skills, template | the tile, a terminal with the skills loaded |-| 1 | + a check that writes `.harness/verdict.json` | + ready or not, findings and phases in the pane header |-| 2 | + a viewer server | + the viewer pane beside the terminal, following the artifact |--#### Worked examples--| Harness | Base | What it shows |-|---|---|---|-| [Marp](https://github.com/autonomous-ai/autonomous-marp) (Slides) | Claude Code | the smallest complete tier 2: a 110-line viewer with live reload and a present mode, two themes, an offline art generator, a check that writes the verdict, node tests. Start here. |-| [Copper](https://github.com/autonomous-ai/autonomous-circuit) (PCB) | Claude Code | a Python toolchain vendored by `setup.sh`, a board viewer, phases Build / Checks / Fab written by the generation pipeline |-| [Solid](https://github.com/autonomous-ai/autonomous-workshop) (3D design) | Codex | a Codex base, CAD scripts as skills, a STEP viewer found through `artifactExtensions`, phases Build / Fit / Print / Motion / Review |--Two rules hold across all of them. The pane is progressive: a harness that only produces a final-file is not one. And the domain stays in the harness: if adding yours needs a change in this repo,-that is a spec change, and [`dsh/spec/README.md`](dsh/spec/README.md) with its schemas is where the-contract lives. Changes to it are appended to `dsh/spec/CHANGES.md`.--## Providers, relay, web--- **`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.--## 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)-dsh/ domain harnesses: the contract and schemas, the registry, the starter, daemon-level tools-```--## Development--```bash-# cli-cd cli && npm install && npm run typecheck && npm test-make install-cli # bundle this tree into ~/.harness/cli and restart the daemon on it--# 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-```--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 demand (Actions -> CI -> Run workflow) and holds-no secrets, which is what lets it run on a fork's branch; 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.+| a **domain harness**: PCB, CAD, slides, yours | [`dsh/README.md`](dsh/README.md), [`dsh/starter-dsh/`](dsh/starter-dsh/) | `harness dsh check .` |+| an **agent** as a CLI engine | [`cli/src/engines/README.md`](cli/src/engines/README.md) | the recorded-session fixtures pass |+| an **agent** as an API provider | [`provider/README.md`](provider/README.md) | the conformance runner, zero failures |+| a **terminal multiplexer** | [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-multiplexer) | `npm run test:tmux-real` |+| a **palette** or terminal theme | [`docs/extending.md`](docs/extending.md#palettes-and-appearance) | `flutter test` |+| a **keymap** | `~/.config/harness/keybindings.jsonc`, no code | it reloads on save |+| **automation** over the daemon | [`docs/cli.md`](docs/cli.md#automation) | the loopback socket answers |++**A domain harness** is a git repository: a manifest, an `AGENTS.md`, skills, a workspace template,+a toolchain that installs itself, and for the pane a viewer server and a verdict file. Harness reads+the manifest and nothing else about its code. Copy the starter, `harness dsh check .`,+`harness dsh install . --link`, and your tile is in New Agent. One registry file in a pull request+lists it for everyone. [Marp](https://github.com/autonomous-ai/autonomous-marp) is the smallest+complete one and the place to start; [Copper](https://github.com/autonomous-ai/autonomous-circuit)+and [Solid](https://github.com/autonomous-ai/autonomous-workshop) are the big ones.++**An agent** is a CLI engine, a normalizer in this repo written from a recorded session of the real+binary, or an API provider, eight JSON-RPC methods on your own infrastructure. Both are first-class:+[docs/extending.md](docs/extending.md).++## Contribute++Harness gets better in more ways than pull requests here.++- **Build a harness for your domain** and list it in [`dsh/registry/`](dsh/registry/). It is a+ product on its own, and it never touches this code.+- **Bring your agent** as an engine or a provider.+- **Record a session.** An engine bug is fixed from a real recorded session of the real binary.+ Attach one to the issue and it is half done.+- **A palette, a terminal theme, a keymap** you are proud of.+- **Docs.** What confused you in the first five minutes is the next fix.++Open an issue before writing an engine or a multiplexer so the shape and the software a maintainer+needs to reproduce it are agreed first. [CONTRIBUTING.md](CONTRIBUTING.md) has the workflow,+[SECURITY.md](SECURITY.md) takes security reports, and the licence is [MIT](LICENSE).## 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).+- [docs/app.md](docs/app.md) — sessions, panes, layouts, terminal, attention, machines+- [docs/keyboard.md](docs/keyboard.md) — the full keymap and the keymap file+- [docs/engines.md](docs/engines.md) — the fourteen engines: how each is followed, resume, bypass, grids+- [docs/architecture.md](docs/architecture.md) — daemon, session model, transport and encryption, relay, providers, the device+- [docs/cli.md](docs/cli.md) — every `harness` command, the dashboard, the loopback socket+- [docs/extending.md](docs/extending.md) — agents, multiplexers, palettes, keys, automation+- [docs/development.md](docs/development.md) — repository layout, build, test, release+- [dsh/README.md](dsh/README.md) — build a domain harness; [dsh/spec/](dsh/spec/README.md) is the contract+- [cli/](cli/README.md), [desktop/](desktop/README.md), [backend/](backend/README.md), [provider/](provider/README.md) — per-package detaildiff --git a/docs/app.md b/docs/app.mdnew file mode 100644index 000000000..566296b15--- /dev/null+++ b/docs/app.md@@ -0,0 +1,68 @@+# The app++What the window does, pane by pane. The keys are in [keyboard.md](keyboard.md).++## Sessions++An agent is one engine process in one tmux pane on one machine. The app calls it an agent. 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 Agent (⌘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 Agent** ends the engine process+and asks first. **Restart Agent** relaunches it in the same pane with the same id, resuming the+conversation where the engine supports it.++**Open Agent (⌘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.++## 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 agent 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).diff --git a/docs/architecture.md b/docs/architecture.mdnew file mode 100644index 000000000..8ffecfdaa--- /dev/null+++ b/docs/architecture.md@@ -0,0 +1,82 @@+# How it works++```+ ( ◉ ) Harness device (USB)+ │+ ┌─────────── this computer ───────────┐+ │ Harness app ── loopback ──▶ harness daemon ──▶ tmux ──▶ claude · codex · … │+ └──────────────────────────────┬──────┘+ │ WebSocket (E2EE)+ ╔═════════╧═════════╗+ ║ Harness Relay ║ store and forward, no keys+ ╚═════════╤═════════╝+ ┌───────────────────────┼───────────────────────┐+ 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+```++**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.++**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.++**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.+- **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.+- **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.++## Providers, relay, web++- **`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 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.++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.diff --git a/docs/cli.md b/docs/cli.mdnew file mode 100644index 000000000..993b80b86--- /dev/null+++ b/docs/cli.md@@ -0,0 +1,49 @@+# 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.diff --git a/docs/development.md b/docs/development.mdnew file mode 100644index 000000000..ffcbd3593--- /dev/null+++ b/docs/development.md@@ -0,0 +1,42 @@+# Development++## 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)+dsh/ domain harnesses: the contract and schemas, the registry, the starter, daemon-level tools+```++## Build and test++```bash+# cli+cd cli && npm install && npm run typecheck && npm test+make install-cli # bundle this tree into ~/.harness/cli and restart the daemon on it++# 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+```++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 demand (Actions -> CI -> Run workflow) and holds+no secrets, which is what lets it run on a fork's branch.+`make remote-machine`+brings up a second machine in Docker so the remote path can be exercised from one laptop.diff --git a/docs/engines.md b/docs/engines.mdnew file mode 100644index 000000000..ae34215e8--- /dev/null+++ b/docs/engines.md@@ -0,0 +1,30 @@+# Engines++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.++| 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.diff --git a/docs/extending.md b/docs/extending.mdnew file mode 100644index 000000000..8c85a513c--- /dev/null+++ b/docs/extending.md@@ -0,0 +1,70 @@+# Extending Harness++Every layer has a contract, a starter and a check. Domain harnesses have their own guide:+[`dsh/README.md`](../dsh/README.md).++## 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) |++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.++```bash+cd cli && npm install && npm run typecheck && npm test # replay the recorded-session fixtures+```++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.++```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>+```++## Add a terminal multiplexer++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 run test:tmux-real # the real multiplexer discovery suite+```++## Palettes and appearance++Six palettes ship — graphite, dusk, midnight, slate, forest, ember — and each coordinates the+workspace chrome with the terminal defaults. They are values of `HarnessPalette` in+[`desktop/lib/shared/theme/color_palette.dart`](../desktop/lib/shared/theme/color_palette.dart); a+new one is one more value there, and it appears in Settings ▸ Appearance on its own. Terminal+colour schemes are `TerminalTheme` values in+[`desktop/lib/terminal/terminal_theme.dart`](../desktop/lib/terminal/terminal_theme.dart). Fonts and+sizes are settings, not code. `cd desktop && flutter test` is the bar.++## Keys++No code: `~/.config/harness/keybindings.jsonc`, watched and reloaded on save. [keyboard.md](keyboard.md)+has the format and the command ids.++## Automation++Anything on the same computer can drive the daemon over its loopback socket, with the same frames the+app and the web client use. [cli.md](cli.md#automation) lists them.diff --git a/docs/keyboard.md b/docs/keyboard.mdnew file mode 100644index 000000000..4ccb0270c--- /dev/null+++ b/docs/keyboard.md@@ -0,0 +1,35 @@+# Keyboard++Every action has a key or a palette entry, and every key can be remapped.++The defaults, in the workspace:++| Keys | Action |+|---|---|+| ⌘N | New Agent |+| ⌘O | Open Agent — 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 agents · 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 | Agents 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.diff --git a/dsh/README.md b/dsh/README.mdindex ab9306231..771db7452 100644--- a/dsh/README.md+++ b/dsh/README.md@@ -12,48 +12,111 @@ is what lets hundreds of DSHs exist without any of them touching this repo.## Anatomy-```-harness.json manifest: id, name, base engine, workspace, agent, toolchain, viewer, verdict-AGENTS.md appended to the agent's instructions in every workspace-skills/ SKILL.md bundles, linked into the workspace-template/ copied into an empty workspace-toolchain/ setup.sh (once, at install) · doctor.sh (exit 0 = ready) · viewer.sh (optional)-viewer/ optional: whatever viewer.sh serves-```+| In the repo | What it is |+|---|---|+| `harness.json` | the manifest: id, name, category, base engine, workspace, skills, toolchain, viewer, verdict path |+| `AGENTS.md` | what the engine is told in every workspace; a `claude` base gets a `CLAUDE.md` that imports it |+| `skills/` | the domain's craft as `SKILL.md` bundles, symlinked into the workspace so edits are live |+| `template/` | a fresh workspace, copied once into an empty folder, plus an optional `init` script |+| `toolchain/setup`, `doctor` | install the domain's tools at install time; say what is missing, one line per check |+| `viewer` | a loopback web server Harness runs beside the terminal; the pane is a webview on it |+| `.harness/verdict.json` | the one file the domain writes and Harness reads: ready or not, findings, phases |-## Tiers+## Build one-| Tier | Ships | Harness shows |-|---|---|---|-| 0 | manifest, AGENTS.md, skills | the tile, the terminal |-| 1 | + scripts that write `.harness/verdict.json` | + a ready chip and findings in the pane header |-| 2 | + a viewer server | + a web pane next to the terminal |+1. **Copy the starter.** [`dsh/starter-dsh/`](starter-dsh/) is a complete tier-0 harness: a+ manifest, an `AGENTS.md`, one skill, a template, a toolchain that installs nothing.++ ```bash+ cp -r dsh/starter-dsh ~/code/my-harness && cd ~/code/my-harness && git init+ ```++ In `harness.json` set `id` (`owner/name`, the install directory and the wire id), `name` (the+ tile), `category` (the tile's second line), `engine` (`claude` or `codex`), and+ `workspace.marker` (a file whose presence means the workspace is already laid out).++2. **Tell the agent its job.** `AGENTS.md` says what the workspace is, where things go, what to do+ first, and how to work so the pane moves: first save within a minute, then build up, check after+ every pass. The craft itself goes in `skills/<name>/SKILL.md`: the dialect, the patterns, the+ commands. Skills are symlinked, so a change in your checkout is live in every workspace.++3. **Lay out the workspace.** `template/` is copied into an empty folder once; then+ `workspace.init` runs with the workspace as its working directory and `HARNESS_DSH_DIR` pointing+ at the install. Seed the first verdict here so the header has a state before the first prompt.++4. **Ship the toolchain with the harness.** `toolchain/setup.sh` runs once at install, in the+ install directory: pin versions and vendor them there (a `node_modules`, a `.venv`), never into+ the user's machine. `toolchain/doctor.sh` exits 0 when the machine can run the harness and prints+ one line per check; Harness shows those lines. Point the agent at the tools through `agent.env`+ (`"MARP_TOOLCHAIN": "${dsh}/toolchain"`); `${dsh}`, `${workspace}` and `${home}` expand.++5. **Write the verdict as a feed.** `.harness/verdict.json` is written at every check and every+ phase change, not at the end. `ready` is the one machine truth; `summary` is the header's line;+ `phases` is how the header says "you are here".-[`starter-dsh/`](starter-dsh/) is tier 0 and the copy-me template. Copper, Solid and Marp are tier 2.+ ```json+ { "spec": 1, "ready": false, "summary": "10 slides so far · 1 warning",+ "findings": [{ "severity": "warning", "kind": "dense", "message": "slide 4 has 61 words" }],+ "artifact": "deck.md",+ "phases": [{ "id": "outline", "name": "Outline", "state": "done" },+ { "id": "draft", "name": "Draft", "state": "active" },+ { "id": "polish", "name": "Polish", "state": "pending" }],+ "updatedAt": "2026-09-15T23:33:00Z" }+ ```-## The contract+6. **Add the viewer.** `viewer.command` is a long-running process. Harness starts it with+ `HARNESS_VIEWER_PORT`, `HARNESS_WORKSPACE`, `HARNESS_DSH_DIR` and `HARNESS_DSH` in its+ environment, waits for the port to open on `127.0.0.1`, then loads `viewer.url` in the pane+ (`${port}` and `${artifact}` expand; the artifact is what the verdict names, or the newest file+ matching `artifactExtensions`). Serve files from the workspace and nothing outside it, watch the+ workspace, push a reload on every change, and re-run your check on every change so the header+ moves while the agent writes without the agent running anything. Marp's viewer does all of this+ in about 110 lines of Node with no dependencies beyond its renderer.-[`spec/README.md`](spec/README.md) is the whole contract: the manifest, the verdict file, what-Harness does at create time, and what it sets in the engine's environment. The JSON Schemas in-[`spec/schema/`](spec/schema/) are normative. The spec is frozen; changes are appended to-[`spec/CHANGES.md`](spec/CHANGES.md).+7. **Check it, install it, run it.**-## Installing+ ```bash+ harness dsh check . # conformance: the manifest, the scripts, the schemas+ harness dsh install . --link # this checkout as the installed harness (a symlink)+ harness dsh doctor owner/name # what the machine is missing, if anything+ harness dsh list # installed here, and what the registry offers+ ```-```bash-harness dsh install autonomous/copper # by registry id-harness dsh install https://github.com/autonomous-ai/autonomous-circuit # by git URL-harness dsh install /path/to/checkout --link # symlink, for development-harness dsh list-harness dsh doctor autonomous/copper-harness dsh check /path/to/checkout # conformance, before publishing-```+ Then New Agent, your tile, a folder, a prompt. For a check without the app,+ [`dsh/tools/dsh-e2e.mjs`](tools/) creates an agent over the daemon's loopback socket and+ reports the materialized workspace, the viewer URL, the pane's environment and the first verdict.+ The viewer process reads its own files when it starts; after you edit it, kill it and the daemon+ respawns it on the new code.-The desktop app offers the same install from New Agent: a harness the machine does not have yet is-installed on Create.+8. **Publish.** Add `dsh/registry/<owner>/<name>.json` in a pull request:-## Publishing+ ```json+ { "id": "owner/name", "name": "Name", "category": "Thing", "description": "One line.",+ "repo": "https://github.com/owner/name", "ref": "main", "engine": "claude",+ "tier": 2, "verified": false }+ ```++ CI clones the repo at that ref and runs the conformance check. Once merged, the app offers the+ tile before the harness is installed and installs it on Create; `verified: true` is for+ first-party entries, everything else shows its git URL on install.++## Tiers++| Tier | Ships | Harness shows |+|---|---|---|+| 0 | manifest, `AGENTS.md`, skills, template | the tile, a terminal with the skills loaded |+| 1 | + a check that writes `.harness/verdict.json` | + ready or not, findings and phases in the pane header |+| 2 | + a viewer server | + the viewer pane beside the terminal, following the artifact |++## Worked examples++| Harness | Base | What it shows |+|---|---|---|+| [Marp](https://github.com/autonomous-ai/autonomous-marp) (Slides) | Claude Code | the smallest complete tier 2: a 110-line viewer with live reload and a present mode, two themes, an offline art generator, a check that writes the verdict, node tests. Start here. |+| [Copper](https://github.com/autonomous-ai/autonomous-circuit) (PCB) | Claude Code | a Python toolchain vendored by `setup.sh`, a board viewer, phases Build / Checks / Fab written by the generation pipeline |+| [Solid](https://github.com/autonomous-ai/autonomous-workshop) (3D design) | Codex | a Codex base, CAD scripts as skills, a STEP viewer found through `artifactExtensions`, phases Build / Fit / Print / Motion / Review |-Add one file under [`registry/<owner>/<name>.json`](registry/) with the repo URL and pinned ref. CI-clones it and runs the conformance check; green merges. First-party entries carry `verified: true`;-everything else shows its git URL and an unverified note on install.+Two rules hold across all of them. The pane is progressive: a harness that only produces a final+file is not one. And the domain stays in the harness: if adding yours needs a change in this repo,+that is a spec change, and [`spec/README.md`](spec/README.md) with its schemas is where the+contract lives. Changes to it are appended to [`spec/CHANGES.md`](spec/CHANGES.md).