A local dashboard for Specification-Driven Development projects.
npx harness-adminYou have 20 specs in flight. Some are done, some are stuck in backlog, a few are actively being worked on — but to know which is which you have to open each directory and read through the files.
Harness reads your changes/ directory and gives you a real-time visual of every spec: grouped by status, task-level progress, archive actions — updated live as you work.
cd your-project
npx harness-adminOpens at http://localhost:3000. Browser launches automatically.
npx harness-admin --tui # terminal UI
npx harness-admin -p 3001 # custom portRequires Node.js 18+
harness # browser dashboard
harness --tui # terminal UI
harness -p 3001 # custom port
harness --config ./harness.config.json # custom config
Harness scans openspec/changes/ for subdirectories. Each one is a change — a unit of work tracked by a tasks.md checklist. Status is derived automatically:
| Status | Condition |
|---|---|
in progress |
at least one [x] and at least one [ ] |
done |
all tasks [x] |
backlog |
no tasks.md or zero checked tasks |
archived |
path is inside the archive directory |
The filesystem is the source of truth. Changes are watched via chokidar and pushed to the browser over WebSocket — no refresh needed.
your-project/
└── openspec/
└── changes/
├── my-feature/
│ ├── proposal.md
│ ├── design.md
│ └── tasks.md
└── archive/
└── shipped-feature/
└── tasks.md
Works with any project that follows this shape — no framework required. Compatible with OpenSpec and any hand-rolled SDD workflow.
Nested changes are supported — a parent directory without its own tasks.md but with sub-directories that have one becomes a group with aggregated progress.
Zero config for OpenSpec projects. To customize, create harness.config.json at your project root:
{
"changesDir": "openspec/changes",
"archiveDir": "openspec/changes/archive",
"tasksFile": "tasks.md",
"proposalFile": "proposal.md",
"designFile": "design.md",
"port": 3000
}Point Harness at multiple projects simultaneously:
{
"projects": [
{ "name": "frontend", "path": "/path/to/frontend" },
{ "name": "api", "path": "/path/to/api" }
]
}A project switcher appears in the sidebar. "All projects" shows a merged view with project badges on each change.
- Grouped sidebar — changes organized by status with collapsible sections
- Live updates — WebSocket pushes filesystem changes to the browser instantly
- Archive from the board — move a change to archive without touching the terminal
- Terminal UI — full
--tuimode with keyboard navigation (↑↓/jk,a,q) - Resizable sidebar — drag the edge to fit your screen
- Nested changes — parent changes aggregate progress across sub-changes
- Multi-repo — monitor multiple projects from a single dashboard
- Claude integration — chat with
proposal.md+design.md+tasks.mdpre-loaded - Apply by task — delegate a specific task to Claude Code from the UI
- Multi-repo improvements — per-project config overrides, consolidated metrics across projects
packages/
├── parser/ Filesystem reader, task parser, status classifier, chokidar watcher
├── server/ Fastify server — REST API, WebSocket, static file serving
├── board/ Browser SPA — Vite + React + Tailwind CSS
├── tui/ Terminal UI — Ink + React
└── cli/ npm entry point — wires everything together
git clone https://github.com/davi-canuto/harness-admin
cd harness-admin
pnpm install
pnpm buildDevelopment against a local project:
# Terminal 1 — API server
cd /path/to/your-project
node /path/to/harness-admin/packages/cli/dist/index.js
# Terminal 2 — board with hot reload
cd /path/to/harness-admin/packages/board
pnpm devEvery change to Harness goes through an OpenSpec change in openspec/changes/. See AGENTS.md for the workflow.
MIT