openharness

# Extending Harness

Every layer has a contract, a starter and a check. Domain harnesses have their own guide:
[`store/README.md`](../store/README.md), which also covers the second kind of package, a **viewer** —
a pane any number of agents point at with `viewer.use` — and the `author` every package names.

## 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. `cli/src/lib/tmuxBackend.ts` is 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.