The Project
Harness Deck is a local dashboard for the output that AI coding agents make for a person to review. An agent publishes a report, mockup, question, approval request, or decision by writing a report.json file. A local Go server finds those files across the projects on a machine, renders each one in the same themed style, and lists them on a live dashboard. Answers travel the other way. The server writes a responses.json file beside the report, and the agent reads it on its next run.
It works with Claude Code, Pi, OpenCode, and Codex across many projects. I use it daily, and it ships through Homebrew. I started it on May 20, 2026, and it has shipped through v0.2.16.
The problem
Coding agents are good at changing a repository, but the material they produce for a person was scattered. It lived in Markdown reports left in chat, one-off HTML mockups, decisions buried in scrollback, and review notes that disappear with the session. None of them had a home. I wanted one local place where any agent could put those artifacts, so that reports, approvals, and decisions would survive a context clear.
Design decisions
The core design choice was to have agents write data instead of markup. A report is a JSON manifest, an ordered list of typed blocks such as prose, table, diff, ask, and approval. The renderer owns the HTML and CSS for every typed block, so reports look the same, and older reports pick up styling changes when the renderer changes. I rejected both agent-written raw HTML, because it gives no consistency guarantee, and an MCP-first design, because it depends on a running server. Raw HTML is confined to an html block, and recurring uses should become typed blocks.
Responses are a file, not a socket. Any harness that can read a directory can pick up an answer, so the agent does not need a live connection. The contract is also versioned. The schema string is harness-deck/report@1. A newer manifest still loads, unknown block types show a visible fallback panel instead of breaking the page, and harness-deck validate rejects versions the binary does not know.
The project has no external dependencies. go.mod has no require block, and CONTRIBUTING.md treats that as a hard constraint. The same choice explains several smaller decisions: JSON config instead of TOML, a two-second polling watcher instead of fsnotify, and Go structs as the schema instead of a separate JSON Schema file.
Safety shapes the renderer as well. The html block renders inside a shadow root, and a <script> tag inside it does not run. Markdown link targets pass through an allowlist, so a javascript: or data: URL in a typed block never becomes a link.
How it works
The server keeps an in-memory index of reports from two places: the central directory at ~/.harness/reports and a .harness/ folder inside each registered project. It rescans every two seconds and uses file modification times, so unchanged reports are skipped. Changes reach open browsers through Server-Sent Events, so the dashboard updates without a reload. Projects are found under configured scan_roots by marker files, with .docs/ai/ as the default marker.
A harness can publish in three ways: write the JSON file directly, use the optional MCP server, or run hdeck new (hdeck is the short alias for harness-deck), optionally with one of five templates. The MCP server exposes tools to publish, validate, list reports, read responses, and update status and live progress. The contract is also compiled into the binary, so hdeck contract prints it on any machine.
When a person answers an ask, the server records the answer, sends a response event, and runs an optional notify command that receives the answer in environment variables. New asks can also fan out to Slack, Discord, or any HTTP webhook. The dashboard also installs on a phone as a PWA over Tailscale, and it can send Web Push to that phone.
Wrap Up
Harness Deck stays narrow on purpose. It is a place for agents to show a person their work, plus a file that carries the answer back. The contract is the piece that holds it together. Any harness that writes the same JSON gets the same page, and the dashboard does not need to know which tool wrote it. CI runs the Go tests with the race detector.