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
Write the README for developers building harnesses
deeadd86a249dad
diff --git a/README.md b/README.mdindex 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.```bashgit clone https://github.com/autonomous-ai/openharness.gitcd openharness@@ -69,24 +45,40 @@ flutter pub getflutter 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:```texthello-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:```bashharness dsh install "$PWD/store/viewers/web-viewer" --link@@ -95,57 +87,71 @@ harness dsh check ../my-first-harnessharness 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 loginharness 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.