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: coding agents, domain-specific harnesses, and the Harness device
deeadf947f588a5
diff --git a/.github/assets/hardware/answer.jpg b/.github/assets/hardware/answer.jpgnew file mode 100644index 000000000..184fa338cBinary files /dev/null and b/.github/assets/hardware/answer.jpg differdiff --git a/.github/assets/hardware/desk-agents.jpg b/.github/assets/hardware/desk-agents.jpgnew file mode 100644index 000000000..8e2f32b11Binary files /dev/null and b/.github/assets/hardware/desk-agents.jpg differdiff --git a/.github/assets/hardware/desk.jpg b/.github/assets/hardware/desk.jpgnew file mode 100644index 000000000..4af47cec5Binary files /dev/null and b/.github/assets/hardware/desk.jpg differdiff --git a/.github/assets/hardware/dimensions.jpg b/.github/assets/hardware/dimensions.jpgnew file mode 100644index 000000000..5a90dca04Binary files /dev/null and b/.github/assets/hardware/dimensions.jpg differdiff --git a/README.md b/README.mdindex 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 getflutter 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 minutesThe [Hello World example](store/examples/hello-world/) is a Codex session that edits an HTML pageshown 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:```bashharness 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 thedesktop/ Flutter app and terminal workspacecli/ TypeScript CLI, daemon, engine adapters, and package runtimebackend/ Relay and control plane-store/ Harnesses, shared viewers, registry, examples, and package spec+store/ Domain-specific harnesses, shared viewers, registry, examples, and package specprovider/ 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.mdindex 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, orpairing 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 hardwarediff --git a/docs/engines.md b/docs/engines.mdindex 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 avendor'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.