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.

README: coding agents, domain-specific harnesses, and the Harness device

deeadf947f588a5
diff --git a/.github/assets/hardware/answer.jpg b/.github/assets/hardware/answer.jpg
new file mode 100644
index 000000000..184fa338c
Binary files /dev/null and b/.github/assets/hardware/answer.jpg differ
diff --git a/.github/assets/hardware/desk-agents.jpg b/.github/assets/hardware/desk-agents.jpg
new file mode 100644
index 000000000..8e2f32b11
Binary files /dev/null and b/.github/assets/hardware/desk-agents.jpg differ
diff --git a/.github/assets/hardware/desk.jpg b/.github/assets/hardware/desk.jpg
new file mode 100644
index 000000000..4af47cec5
Binary files /dev/null and b/.github/assets/hardware/desk.jpg differ
diff --git a/.github/assets/hardware/dimensions.jpg b/.github/assets/hardware/dimensions.jpg
new file mode 100644
index 000000000..5a90dca04
Binary files /dev/null and b/.github/assets/hardware/dimensions.jpg differ
diff --git a/README.md b/README.md
index 7ce80e3ab..bee187948 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,64 @@
# OpenHarness
-An open-source framework for running coding agents with domain-specific tools and live viewers.
+**The open-source stack for AI agents, from the terminal to your desk.**
-OpenHarness runs Claude Code, Codex, OpenCode, and other engines in persistent terminal sessions.
-A **harness** adds instructions, tools, a project template, and a viewer for the output. You chat
-with the agent on the right; the model, board, game, or document updates on the left. The viewer
-stays interactive while the agent works and after it finishes.
+OpenHarness runs Claude Code, Codex, and a dozen more coding agents in persistent terminals on every
+machine you own. **Domain-specific harnesses (DSH)** turn those agents into specialists that design
+circuit boards, model 3D parts, simulate robots, and build games, each with a live viewer. The
+**Harness device** puts all of it on your desk. Software and hardware, end to end, in one repository.
-The package format is small on purpose: a folder and a `harness.json`. If you've wired a coding
-agent to a tool you use, you can package that workflow without changing the desktop app.
+[Run it](#run-it) · [Domain-specific harnesses](#domain-specific-harnesses-dsh) ·
+[Harness device](#harness-device) · [Architecture](docs/architecture.md) · [Contribute](#contributing)
-[Install](#run-it) · [Make a harness](#make-a-harness) · [Architecture](docs/architecture.md) ·
-[Contribute](CONTRIBUTING.md)
+<p align="center">
+ <img src=".github/assets/hardware/desk-agents.jpg" width="960" alt="The Harness device on a desk beside a keyboard, with the coding agents it runs: Claude Code, Codex, Cursor, OpenCode, Pi, Hermes, Command Code, Devin, Muse Code, Amp, Antigravity, GitHub Copilot, Grok Build and Kilo Code">
+</p>
+
+## Coding agents, on every machine
+
+The coding agent is still the heart of the work, and OpenHarness is built around it.
+
+- **Real terminals that outlive the window.** Every agent runs in a persistent tmux session. Close the
+ app and the agents keep working; if tmux goes down with a reboot, the daemon brings the panes back and
+ resumes the sessions.
+- **Every engine, no wrappers.** Claude Code, Codex, Cursor, OpenCode, Pi, Hermes, Command Code, Devin,
+ Muse Code, Amp, Kilo, Grok Build, Antigravity and GitHub Copilot. OpenHarness reads the transcript each
+ agent already writes and installs the vendor's own hooks. Your credentials stay in `~/.claude`, `~/.codex` and
+ so on. See the [engine list](docs/engines.md).
+- **All your machines in one window.** The laptop, the Mac mini at home, the server in the rack. Each
+ runs a daemon with outbound connections only. Terminal traffic is end-to-end encrypted, the relay only
+ forwards ciphertext, and it goes peer to peer over WebRTC when it can. No SSH server, VPN, or open
+ port.
+- **Built for many agents at once.** Split panes, a keyboard-driven layout, fuzzy search across
+ sessions and machines (**⌘O**), and one shortcut to the agents waiting on you (**⇧⌘I**). The
+ [workspace guide](docs/app.md) and [keybindings](docs/keyboard.md) cover the rest.
<p align="center">
<img src=".github/assets/screenshots/harness.gif" width="960" alt="Agent terminals alongside live CAD, PCB, and slide viewers">
</p>
-## Run it
+### Run it
-1. [Download the desktop app](https://harness.autonomous.ai/desktop).
-2. Set up a supported coding engine with your own subscription, API key, or local model configuration.
-3. Install a harness from the Store. Press **⌘N**, choose the harness, machine, and project, and start a session.
+1. [Download the desktop app](https://harness.autonomous.ai/desktop) for macOS or Linux.
+2. Sign in to a coding agent you already use, with your own subscription, API key, or local model.
+3. Press **⌘N**, pick an agent or a harness, a machine and a project, and start.
-**Current support:** macOS is the primary tested platform, including embedded viewers. Linux builds
-exist, but feature parity is in progress. Windows support is also work in progress.
+On another machine:
-**Current limitation:** desktop and daemon startup still require a Harness account.
-[Account-free local use is tracked](docs/development.md#account-free-local-use); sign-in should
-only be necessary to link remote machines. Engine authentication is separate.
+```bash
+curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
+harness login
+harness start
+```
+
+Then **Machines → Link Machine** in the app.
+
+macOS is the primary tested platform. Linux builds exist and feature parity is in progress; Windows is
+work in progress. The app and daemon still need a Harness account to start;
+[account-free local use is tracked](docs/development.md#account-free-local-use).
-### Build from source
+<details>
+<summary><b>Build from source</b></summary>
For macOS, install Node.js 20+, tmux, Xcode, and Flutter 3.47+ / Dart 3.13+:
@@ -45,11 +73,90 @@ flutter pub get
flutter run -d macos
```
-`make install-cli` installs this checkout's CLI and restarts the local daemon.
-The [development guide](docs/development.md) covers tests and isolated environments.
-Individual harnesses may need additional tools; their setup and doctor commands handle those checks.
+`make install-cli` installs this checkout's CLI and restarts the local daemon. The
+[development guide](docs/development.md) covers tests and isolated environments.
-## Make a harness
+</details>
+
+### How it fits together
+
+```mermaid
+flowchart LR
+ device["Harness device"] -- USB --> daemon
+ app["Harness app<br/>(Flutter)"] -- loopback --> daemon["harness daemon<br/>(TypeScript)"]
+ daemon --> tmux["tmux"] --> agents["Claude Code · Codex · OpenCode · …"]
+ daemon --> dsh["DSH toolchain<br/>+ live viewer"]
+ daemon <-- "E2EE · WebRTC" --> relay["Harness relay"]
+ relay <--> remote["daemons on your<br/>other machines"]
+```
+
+The [architecture guide](docs/architecture.md) covers the daemon, the session model, transport and
+encryption.
+
+## Domain-specific harnesses (DSH)
+
+A **domain-specific harness** turns a coding agent into a specialist. It brings the domain's
+instructions and skills, a pinned toolchain, a project template, a verdict the app can read, and a
+**live viewer** for what the agent makes. You chat on one side; the board, the part, the robot or the
+game takes shape on the other, and stays interactive after the agent is done.
+
+A DSH is a folder with a `harness.json`. The agent does the reasoning; the harness brings the tools
+and the view. Adding a domain never needs a change to the app or the daemon.
+
+<table>
+ <tr>
+ <td width="33%" valign="top">
+ <a href="store/agents/autonomous-circuit/"><img src="store/showcase/autonomous-circuit/six-key-macropad.jpg" alt="A six-key USB macropad PCB in 3D"></a>
+ <b>Autonomous Circuit</b><br/><sub><i>“Design a six-key USB macropad. Start with the schematic.”</i> A fab-ready board: RP2040, 43 parts.</sub>
+ </td>
+ <td width="33%" valign="top">
+ <a href="store/agents/text-to-cad/"><img src="store/showcase/text-to-cad/planetary-gear-set.jpg" alt="A planetary gear set in the CAD viewer"></a>
+ <b>text-to-cad</b><br/><sub><i>“Design a 3D-printable planetary gear set: a 12-tooth sun, three 18-tooth planets…”</i> Nine parts, zero interference.</sub>
+ </td>
+ <td width="33%" valign="top">
+ <a href="store/agents/mujoco/"><img src="store/showcase/mujoco/g1-humanoid-hello.jpg" alt="A Unitree G1 humanoid waving in MuJoCo"></a>
+ <b>MuJoCo</b><br/><sub><i>“Make the Unitree G1 humanoid say hello: stand, raise its right hand and wave…”</i> A 29-servo rollout.</sub>
+ </td>
+ </tr>
+ <tr>
+ <td width="33%" valign="top">
+ <a href="store/agents/blender/"><img src="store/showcase/blender/cozy-reading-nook.jpg" alt="An isometric reading nook rendered in Blender"></a>
+ <b>Blender</b><br/><sub><i>“Make a cozy isometric reading nook: a cut-away corner of a room with an armchair…”</i> 122 named objects.</sub>
+ </td>
+ <td width="33%" valign="top">
+ <a href="store/agents/godogen/"><img src="store/showcase/godogen/neon-drift.jpg" alt="A synthwave hoverbike racing game"></a>
+ <b>Godogen</b><br/><sub><i>“Make a synthwave hoverbike racer: ride down a neon grid canyon toward a striped setting sun…”</i> Playable in the pane.</sub>
+ </td>
+ <td width="33%" valign="top">
+ <a href="store/agents/manim/"><img src="store/showcase/manim/fourier-knight.jpg" alt="A chess knight traced by Fourier epicycles"></a>
+ <b>Manim</b><br/><sub><i>“Draw a chess knight using nothing but spinning circles…”</i> 120 epicycles in gold.</sub>
+ </td>
+ </tr>
+</table>
+
+Every picture is real output from the harness's own toolchain, and the prompt is the one that made it.
+
+### 18 harnesses today
+
+| Domain | Harnesses |
+|---|---|
+| CAD | [Autonomous Workshop](store/agents/autonomous-workshop/), [text-to-cad](store/agents/text-to-cad/) |
+| 3D | [Blender](store/agents/blender/) |
+| Electronics | [Autonomous Circuit](store/agents/autonomous-circuit/), [CircuitJS](store/agents/circuitjs/), [Yosys](store/agents/yosys/) |
+| Games | [Godogen](store/agents/godogen/), [Phaser](store/agents/phaser/) |
+| Documents and diagrams | [Marp](store/agents/marp/), [Typst](store/agents/typst/), [Excalidraw](store/agents/excalidraw/) |
+| Video and music | [OpenMontage](store/agents/openmontage/), [Remotion](store/agents/remotion/), [Manim](store/agents/manim/), [Strudel](store/agents/strudel/) |
+| Simulation and analysis | [MuJoCo](store/agents/mujoco/), [RDKit](store/agents/rdkit/), [marimo](store/agents/marimo/) |
+
+Each one wraps an open-source project under its own name, credits it, pins its toolchain, and installs
+on a fresh machine from the Harness Store. Eight [shared viewers](store/viewers/) (CAD, 3D models,
+documents, games, film, video, MuJoCo, web) mean a new harness rarely needs to write its own.
+
+**The harness we'd love to see next is the one for the tool you use.** KiCad, FreeCAD, OpenSCAD, Godot,
+Jupyter, QGIS, Home Assistant, LilyPond, Inkscape — or your own company's toolchain. A harness can live
+in this repository or in yours.
+
+### Your first DSH in ten minutes
The [Hello World example](store/examples/hello-world/) is a Codex session that edits an HTML page
shown in the shared Web Viewer:
@@ -78,7 +185,8 @@ Its manifest connects the pieces:
}
```
-From this checkout, with the `harness` CLI installed:
+The CLI and the package protocol call a harness a DSH, so the commands are `harness dsh …`. From this
+checkout, with the `harness` CLI installed:
```bash
harness dsh install "$PWD/store/viewers/web-viewer" --link
@@ -88,106 +196,58 @@ harness dsh install ../my-first-harness --link
```
Press **⌘N → Hello World**, choose a new project, and ask it to “Say hello to Ada.” The agent edits
-`index.html`; the viewer reloads. Change `AGENTS.md` to try another workflow, then start a new
-session. Add skills, setup scripts, and checks as needed.
-
-The first install command links the viewer from your checkout. Normal Store installs resolve
-viewer dependencies automatically and reuse viewers already installed on that machine.
-`--link` keeps the package connected to your source directory.
-
-The [authoring guide](store/README.md) covers the full manifest, toolchains, live progress,
-verification, and publishing. DSH means *domain-specific harness*; that's the name used by the CLI
-and package protocol.
+`index.html`; the viewer reloads. Change `AGENTS.md` to try another workflow, then start a new session.
+`--link` keeps the package connected to your source directory; Store installs resolve viewer
+dependencies on their own.
-### The pieces
+The [authoring guide](store/README.md) covers the full manifest, toolchains, live progress, verdicts,
+store pages, and publishing; the [package specification](store/spec/README.md) is the contract.
| Piece | Responsibility |
|---|---|
-| Engine | Runs the coding agent: Claude Code, Codex, OpenCode, etc. |
-| Harness | Packages a workflow: engine, instructions, tools, workspace, and optional viewer |
-| Viewer | Displays and interacts with project output; can be shared by harnesses |
-| Session | One running agent in a project on a machine |
+| Engine | Runs the coding agent: Claude Code, Codex, OpenCode, and the rest |
+| Harness (DSH) | Packages a domain: engine, instructions, toolchain, workspace, and viewer |
+| Viewer | Shows and interacts with what the agent makes; shared across harnesses |
+| Session | One running agent, in one project, on one machine |
-Domain code stays in the package. The platform reads the manifest, prepares the workspace, starts
-the processes, and watches the declared verdict file. Adding a harness on an existing engine
-shouldn't require a change to the app or daemon.
+## Harness device
-## Existing harnesses
-
-The packages in [`store/agents/`](store/agents/) wrap these tools and workflows:
-
-| Domain | Packages |
-|---|---|
-| CAD | [Autonomous Workshop](store/agents/autonomous-workshop/), [text-to-cad](store/agents/text-to-cad/) |
-| 3D | [Blender](store/agents/blender/) |
-| Electronics | [Autonomous Circuit](store/agents/autonomous-circuit/), [CircuitJS](store/agents/circuitjs/), [Yosys](store/agents/yosys/) |
-| Games | [Phaser](store/agents/phaser/) |
-| Documents and diagrams | [Marp](store/agents/marp/), [Typst](store/agents/typst/), [Excalidraw](store/agents/excalidraw/) |
-| Video and music | [Remotion](store/agents/remotion/), [Manim](store/agents/manim/), [Strudel](store/agents/strudel/) |
-| Simulation and analysis | [MuJoCo](store/agents/mujoco/), [RDKit](store/agents/rdkit/), [marimo](store/agents/marimo/) |
-
-Each package credits its upstream project and documents its dependencies and license.
-The [engine list](docs/engines.md) covers the coding CLIs the platform can launch.
+<p align="center">
+ <img src=".github/assets/hardware/answer.jpg" width="960" alt="A finger taps the round Harness device to answer an agent that redesigned the billing controls">
+</p>
-## Terminal workspace
+No other agent stack ships this layer. The **Harness device** is a round, always-on display that sits beside
+your keyboard and shows your agents at a glance: what each one is doing, which one has finished, and
+which one is waiting on you. Read a question and answer it on the screen, or tap and speak a new task,
+without switching windows.
-The desktop app uses real terminals backed by persistent tmux sessions. Closing the window does
-not end the agents. Panes can contain terminals or viewers, and the layout is keyboard-driven.
+It is open hardware, all the way down. This repository has everything it takes to build one:
-| Shortcut | Action |
+| Layer | What's here |
|---|---|
-| **⌘N** | Start a harness |
-| **⌘O** | Fuzzy-find sessions, projects, tabs, and machines; `>` opens commands |
-| **⌘H / J / K / L** | Move between panes |
-| **⌘Enter** | Zoom a pane or restore the layout |
-| **⌘R / ⌘D** | Split right / down |
-| **⌘S** | Choose a layout |
-| **⇧⌘I** | Find agents waiting for input |
-
-[Keybindings](docs/keyboard.md) are configurable. See the [workspace guide](docs/app.md) for tabs,
-layouts, search, and session behavior.
-
-## Multiple machines
-
-Each machine runs a daemon that makes outbound connections. Linked machines use end-to-end
-encryption for terminal traffic; the relay forwards ciphertext. Direct WebRTC connections are
-used when available. No SSH server, VPN, or inbound port forwarding is required.
-
-On another supported machine:
-
-```bash
-curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
-harness login
-harness start
-```
-
-Use **Machines → Link Machine** in the app to link it.
-The [architecture docs](docs/architecture.md) describe transport, identity, and encryption.
-
-## Device firmware
-
-[`devices/harness-device/firmware/`](devices/harness-device/firmware/) contains ESP32-S3 firmware for a round USB companion display.
-It shows agent status and supports responses and voice input through the host daemon.
-The device connects over USB; it doesn't need Wi-Fi credentials.
+| [Firmware](devices/harness-device/firmware/) | ESP32-S3, ESP-IDF, a 466 × 466 round AMOLED with touch, microphones and audio. Connects to the host's daemon over USB — no Wi-Fi setup, no account on the device. |
+| [PCB](devices/harness-device/hardware/pcb/) | The EasyEDA Pro project, the schematic, Gerbers, the bill of materials, and pick-and-place data for assembly. |
+| [Enclosure](devices/harness-device/hardware/3d/) | STEP for editing and STL for printing: the housing, an iron counterweight base, the USB clamp, and the button. |
-Build and flash it onto a supported board, or add a board port. Schematics and enclosure designs
-are not in the repository yet. The [hardware guide](devices/harness-device/firmware/README.md) lists the current
-boards and build commands.
+[**Get a Harness device**](https://www.autonomous.ai/harness), or build your own from these files. The
+[firmware guide](devices/harness-device/firmware/README.md) lists the supported boards and build
+commands, and the [hardware guide](devices/harness-device/hardware/README.md) covers the design files.
https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c
## Contributing
-A good first PR is a harness for a tool you already use. Start with the example, make one workflow
-work end to end, and include a reproducible project. Pin the toolchain, credit upstream, and show
-what someone can inspect or interact with in the viewer.
+There are three ways in, one for each layer of the stack.
-Packages can live in this repository or your own. You don't need to modify the platform to share
-one. The [contribution guide](CONTRIBUTING.md) walks through both paths.
+- **Make a DSH for a tool you use.** Start from Hello World, make one workflow work end to end, pin the
+ toolchain, credit the upstream project, and show something worth looking at in the viewer.
+- **Improve the coding workspace.** Terminal behavior, engine support, the daemon, the relay, Linux and
+ Windows.
+- **Hack the hardware.** Port the firmware to another board, remix the enclosure, add a feature to the
+ device.
-There's platform work too: terminal behavior, engine support, viewers, accessibility, Linux and
-Windows support, and hardware ports. Small fixes and notes about something that didn't work are
-useful contributions. Bring a workflow, try it, and help make it easier for the next person to use.
+Small fixes and notes about something that didn't work are welcome too. The
+[contribution guide](CONTRIBUTING.md) walks through each path.
## Repository map
@@ -195,14 +255,14 @@ useful contributions. Bring a workflow, try it, and help make it easier for the
desktop/ Flutter app and terminal workspace
cli/ TypeScript CLI, daemon, engine adapters, and package runtime
backend/ Relay and control plane
-store/ Harnesses, shared viewers, registry, examples, and package spec
+store/ Domain-specific harnesses, shared viewers, registry, examples, and package spec
provider/ Provider API contract, implementations, and conformance tests
-devices/ Device firmware
+devices/ Harness device firmware, PCB, and enclosure
```
-- [Development and testing](docs/development.md) · [Extension points](docs/extending.md)
-- [Package specification](store/spec/README.md) · [CLI and automation](docs/cli.md)
+- [Development and testing](docs/development.md) · [Extension points](docs/extending.md) · [CLI and automation](docs/cli.md)
- [Desktop](desktop/README.md) · [Daemon](cli/README.md) · [Relay](backend/README.md) · [Provider API](provider/README.md)
- [Security policy](SECURITY.md) · [License](LICENSE)
-The app, framework, and firmware are MIT licensed. Upstream tools, models, and assets keep their own licenses.
+The repository is MIT licensed unless a folder says otherwise. Upstream tools, models, and assets keep
+their own licenses.
diff --git a/devices/harness-device/firmware/README.md b/devices/harness-device/firmware/README.md
index 14885560a..98abcb1c7 100644
--- a/devices/harness-device/firmware/README.md
+++ b/devices/harness-device/firmware/README.md
@@ -8,7 +8,7 @@ flash a supported board, or contribute a hardware port.
the cable. The current firmware has no Wi-Fi setup, backend connection, account credentials, or
pairing code. Plugging the device into the host establishes the connection.
-Schematics and enclosure designs are coming; they are not included in this repository yet.
+The schematic, PCB and enclosure designs are in [`../hardware/`](../hardware/).
## Supported hardware
diff --git a/docs/engines.md b/docs/engines.md
index ae34215e8..8803f97c1 100644
--- a/docs/engines.md
+++ b/docs/engines.md
@@ -4,10 +4,10 @@ Harness never wraps an agent. It reads the transcript the agent already writes a
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 |
+| Engine | Binary | How Harness follows it | Resume | Auto-approve | 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 |
+| Claude Code | `claude` | hooks in `~/.claude/settings.json` + JSONL transcript | `--resume` | `--permission-mode auto` | yes |
+| Codex | `codex` | `hooks.json` per `CODEX_HOME` + JSONL rollouts | `resume` | `--approve-for-me` | yes |
| Cursor | `cursor-agent` | `~/.cursor/hooks.json` + transcript | `--resume` | `--force` | — |
| OpenCode | `opencode` | plugin + SQLite | `--session` | `--auto` | yes |
| Pi | `pi` | extension + transcript | `--session` | — | yes |
@@ -21,6 +21,10 @@ vendor's own hooks or plugin to learn when a turn starts and ends. Your credenti
| Antigravity | `agy` | hooks + transcript | `--conversation` | — | — |
| GitHub Copilot | `copilot` | hooks + transcript | `--resume` | — | yes |
+**Auto-approve** is the default permission mode for a new harness: the engine's own auto mode, not its
+skip-every-check flag. New Harness ▸ Advanced offers the engine's other modes (`PERMISSION_MODES` in
+`cli/src/lib/engineLaunch.ts`).
+
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.