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.

Write the README for developers building harnesses

deeadd86a249dad
diff --git a/README.md b/README.md
index e504acba2..8c6d95a39 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,39 @@
# OpenHarness
-**An open-source framework for building, sharing, and running AI harnesses.**
+An open-source framework for running coding agents with domain-specific tools and live viewers.
-Design your first 3D model. Make a circuit board. Build a game. Create something you couldn't make
-before. **Agent + viewer = harness.** The agent gets the instructions, tools, and workspace for a new craft;
-the viewer lets you watch the result take shape.
+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.
-Choose your engine. Install the harnesses you need. Run them on your own computers. Build the next
-one and share it with everyone. The app, framework, and device firmware are open source under [MIT](LICENSE).
+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.
-[Get started](#get-started) · [Build your first harness](#build-your-first-harness) ·
-[Contribute](CONTRIBUTING.md) · [Documentation](#documentation)
+[Install](#run-it) · [Make a harness](#make-a-harness) · [Architecture](docs/architecture.md) ·
+[Contribute](CONTRIBUTING.md)
<p align="center">
- <img src=".github/assets/screenshots/harness.gif" width="960" alt="Coding agents side by side, a 3D case taking shape in CAD, a circuit board shown as a schematic and in 3D, and a live slide deck—all beside the terminals creating them">
+ <img src=".github/assets/screenshots/harness.gif" width="960" alt="Agent terminals alongside live CAD, PCB, and slide viewers">
</p>
-## More harnesses. More superpowers.
+## Run it
-The [Harness Store](store/README.md) already includes these capabilities. Pick one, give it a
-project, and start making. Add and remove harnesses as your interests change.
+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.
-| What would you like to make? | Harnesses to explore |
-|---|---|
-| A printable part or a product prototype | [Autonomous Workshop](store/agents/autonomous-workshop/), [text-to-cad](store/agents/text-to-cad/) |
-| A 3D scene or animation | [Blender](store/agents/blender/) |
-| A circuit board, simulated circuit, or digital chip | [Autonomous Circuit](store/agents/autonomous-circuit/), [CircuitJS](store/agents/circuitjs/), [Yosys](store/agents/yosys/) |
-| A game you can play | [Phaser](store/agents/phaser/) |
-| A keynote, document, or diagram | [Marp](store/agents/marp/), [Typst](store/agents/typst/), [Excalidraw](store/agents/excalidraw/) |
-| A video, mathematical animation, or music | [Remotion](store/agents/remotion/), [Manim](store/agents/manim/), [Strudel](store/agents/strudel/) |
-| A robot simulation, molecular model, or interactive notebook | [MuJoCo](store/agents/mujoco/), [RDKit](store/agents/rdkit/), [marimo](store/agents/marimo/) |
-
-Use **Codex, Claude Code, OpenCode**, or another [supported coding engine](docs/engines.md).
-Each specialized harness declares the engine it uses. Your engine keeps its own login, configuration,
-and model access; OpenHarness adds the workspace around it. Shared viewers are installed as
-dependencies and reused by other harnesses on the same machine.
-
-These capabilities build on the work of upstream open-source communities. The Store credits their
-authors and links to their projects. Each project's own license still applies.
+**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.
-## Get started
+**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.
-1. [Download the app](https://harness.autonomous.ai/desktop).
-2. Open the Harness Store and choose something you want to make. Set up the coding engine it uses
- with your own subscription, API key, or supported local model configuration.
-3. Press **⌘N**, choose a harness, machine, and project, then create your session.
+### Build from source
-**macOS first.** macOS is our primary supported and tested desktop experience. Linux builds exist,
-but feature parity is still in progress; Windows support is planned. Embedded harness viewers
-currently work on macOS. Individual harnesses may have additional toolchain requirements.
+For macOS, install Node.js 20+, tmux, Xcode, and Flutter 3.47+ / Dart 3.13+:
-**Current limitation:** startup still requires sign-in. [Account-free local use is an outstanding
-requirement](docs/development.md#account-free-local-use): sign-in should only be needed when you
-link remote machines. Your coding engine's own authentication is separate.
-
-<details>
-<summary>Build and run from source</summary>
-
-You will need Node.js 20+, tmux, Xcode, and Flutter 3.47+ with Dart 3.13+ for macOS.
```bash
git clone https://github.com/autonomous-ai/openharness.git
cd openharness
@@ -69,24 +45,40 @@ flutter pub get
flutter run -d macos
```
-`make install-cli` installs this checkout's CLI and restarts the local daemon. See the
-[development guide](docs/development.md) for isolated testing and the other packages.
-
-</details>
+`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.
-## Build your first harness
+## Make a harness
-**Your first harness can be a greeting in a live preview.** You don't need to change the desktop
-app or learn its codebase. The [Hello World example](store/examples/hello-world/) contains:
+The [Hello World example](store/examples/hello-world/) is a Codex session that edits an HTML page
+shown in the shared Web Viewer:
```text
hello-world/
- harness.json the agent, instructions, and shared viewer
- AGENTS.md what this harness helps someone do
- template/index.html the page you will see beside the terminal
+ harness.json
+ AGENTS.md # instructions for the agent
+ template/index.html # copied into a new project
```
-From a checkout, with the `harness` CLI installed:
+Its manifest connects the pieces:
+
+```json
+{
+ "spec": 1,
+ "id": "examples/hello-world",
+ "name": "Hello World",
+ "engine": "codex",
+ "workspace": {
+ "template": "template",
+ "marker": "index.html"
+ },
+ "agent": { "instructions": "AGENTS.md" },
+ "viewer": { "use": "autonomous/web-viewer" }
+}
+```
+
+From this checkout, with the `harness` CLI installed:
```bash
harness dsh install "$PWD/store/viewers/web-viewer" --link
@@ -95,57 +87,71 @@ harness dsh check ../my-first-harness
harness dsh install ../my-first-harness --link
```
-The first command links the shared viewer from this checkout; Store installs resolve viewer
-dependencies automatically. The connection is declared in `harness.json`:
+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.
-```json
-"viewer": { "use": "autonomous/web-viewer" }
-```
+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.
-Open **⌘N → Hello World**, choose a new project, and ask **“Say hello to Ada.”** Codex edits
-`index.html`, and the greeting changes in the built-in Web Viewer beside it. Change the instructions
-to teach it your own craft, then start a fresh session to try them. Add skills, setup scripts, or
-checks when you need them; the viewer is already shared with other harnesses.
+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.
-The terms describe different parts of the same experience:
+### The pieces
-| Term | Meaning | Example |
-|---|---|---|
-| **Engine** | The coding agent that does the work | Codex |
-| **Viewer** | The preview that shows what the agent makes | A 3D viewport |
-| **Harness** | An agent and viewer packaged for a craft | Autonomous Workshop for CAD |
-| **Session** | One running instance in a project, on a machine | Designing your phone stand |
+| 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 |
+
+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.
+
+## 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/) |
-The [`harness dsh` commands](store/README.md) keep their existing name; DSH means domain-specific
-harness. [The contribution guide](CONTRIBUTING.md#your-first-harness) takes you from Hello World to
-a harness other people can install from your repository or find in the Store.
+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.
-## A terminal you already know
+## Terminal workspace
-Native Flutter, real terminals, persistent tmux sessions. Keep your familiar CLI workflows and
-bring several agents together in one window, with their outputs beside them.
+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.
-| Shortcut | What it does |
+| Shortcut | Action |
|---|---|
-| **⌘N** | Start a harness: choose what, where, and which project |
-| **⌘O** | Fuzzy-find sessions, projects, tabs, and machines; type `>` for commands |
+| **⌘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, then return to the layout |
+| **⌘Enter** | Zoom a pane or restore the layout |
| **⌘R / ⌘D** | Split right / down |
| **⌘S** | Choose a layout |
-| **⇧⌘I** | Find agents waiting for your attention |
+| **⇧⌘I** | Find agents waiting for input |
-Your sessions live on the machine, independently of the window. Close the app and return to your
-work. [Customize your keybindings](docs/keyboard.md) or explore the [workspace guide](docs/app.md).
+[Keybindings](docs/keyboard.md) are configurable. See the [workspace guide](docs/app.md) for tabs,
+layouts, search, and session behavior.
-## Your machines, together
+## Multiple machines
-Use your laptop, the Mac mini at home, and a remote workstation from the same window. Each machine
-runs a daemon that connects outward: no SSH setup, VPN, or inbound port forwarding.
-
-Linked machines use end-to-end encryption for terminal traffic. The relay forwards ciphertext;
-direct WebRTC connections are used when available. Sign in and explicitly link the machines you
-want to use. [How the connection works](docs/architecture.md).
+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:
@@ -155,41 +161,48 @@ harness login
harness start
```
-Then use **Machines → Link Machine** in the app.
+Use **Machines → Link Machine** in the app to link it.
+The [architecture docs](docs/architecture.md) describe transport, identity, and encryption.
+
+## Device firmware
-## Open firmware. Your hardware.
+[`device/harness/`](device/harness/) 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.
-A round USB display brings your agents onto your desk: see their progress, answer questions, and
-speak a task. It connects to the host daemon over the cable, with no Wi-Fi setup or credentials
-stored on the device.
+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](device/harness/README.md) lists the current
+boards and build commands.
https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c
-The [ESP32-S3 firmware](device/harness/) is available now. Build and flash it onto a supported
-board, or contribute support for yours. **Schematics and enclosure designs are coming**; they are
-not included yet. The [hardware guide](device/harness/README.md) covers the current boards and build.
+## Contributing
-## Help build OpenHarness
+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.
-The community's building block is a **harness**. Bring a tool you love, a workflow you know well,
-or a craft you want more people to try. Someone else's first PCB, game, or animation could start
-with what you contribute.
+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.
-- **Add a harness:** [start with Hello World](CONTRIBUTING.md#your-first-harness), then share a
- working example. It can live here or in your own repository.
-- **Improve one:** better instructions, a sample project, a clearer error, a new viewer, or support
- for another operating system all help.
-- **Improve the platform:** engines, terminal behavior, accessibility, keyboard workflows, and
- hardware ports are welcome too. [Find your starting point](CONTRIBUTING.md#other-ways-to-contribute).
-- **Tell us what was confusing:** documentation fixes and reproducible bug reports are contributions.
+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.
-You can use OpenHarness, build a harness privately, or fork the whole platform. Sharing yours
-helps the next person do more. [Contribute](CONTRIBUTING.md) · [Report a security issue](SECURITY.md).
+## Repository map
-## Documentation
+```text
+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
+provider/ Provider API contract, implementations, and conformance tests
+device/ Device firmware
+```
-- [Build and share harnesses](store/README.md) · [Package specification](store/spec/README.md)
-- [Workspace](docs/app.md) · [Keyboard shortcuts](docs/keyboard.md) · [Coding engines](docs/engines.md)
-- [Architecture and encryption](docs/architecture.md) · [CLI and automation](docs/cli.md)
-- [Build, test, and develop](docs/development.md) · [Extension points](docs/extending.md)
+- [Development and testing](docs/development.md) · [Extension points](docs/extending.md)
+- [Package specification](store/spec/README.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.