hud

hud is one local server with a browser board. The canvas is for monitors (with their frames, notes and utilities); the work itself lives in a ticket tree. The board grants exclusive leases, takes work back from an agent that goes silent, and treats a ticket tree as the owned decomposition of a job. Agents reach it through MCP, the CLI or HTTP. It runs on your machine, binds to loopback only, and keeps your data in a per-user directory. The contract is PRODUCT.md.

People start with the human quickstart; agents use GUIDE.md.

Install

curl -fsSL https://raw.githubusercontent.com/CodeKnight314/hud/main/scripts/install.sh | sh

Windows (PowerShell): irm https://raw.githubusercontent.com/CodeKnight314/hud/main/scripts/install.ps1 | iex

The installer downloads the latest stable release from GitHub Releases, checks it against the release's SHA256SUMS, and puts hud in ~/.hud/bin, adding it to PATH (a symlink into a PATH directory, otherwise a marked block in your shell rc; HUD_NO_PATH_EDIT=1 skips that). It needs Node.js 18 or newer; there is no app bundle and no code signing. Then:

hud            # start the server if needed and open the board in your browser
hud status     # pid, port, data dir, save health
hud update     # install the next release (same checksum check); --check only reports

From a checkout: npm install, then npm run dev (Electron on a scratch port) or node bin/hud.js.

Related MCP server: KittyClaw

What you get

• Tickets with real structure. A project key gives its tickets KEY-n idents; a parent owns its decomposition. Dependencies, assignees, decisions and a live tree (or list) view; a run ticket can summarize a whole job.

• Monitors that stay honest. Command, HTTP, probe and cron-heartbeat sources with thresholds, staleness, history, 24 h uptime and alerts. Readings carry provenance, evidence and freshness.

• A live board. Frames, notes, utilities, annotations, comparisons, and a fixed 1600 × 900 surface that you and agents arrange together.

• Needs you. One badge for agent questions, command approvals, monitor errors and tickets blocked on you.

• Coordination for several agents. The board enforces exclusive leases. A silent agent loses its hold, and a live lease stays with its holder. A queue, typed context, attachments and an event-driven wait let agents share findings.

Connect an agent

hud mcp install        # register hud with Claude Code, Codex and OpenCode
hud mcp status         # what is configured where
hud mcp print generic  # a snippet for any other MCP client

hud mcp install registers the installed launcher, so a client never depends on PATH. Agents get the full surface, documented in the guide (hud guide, hud://guide, GET /api/guide). hud guide --section <anchor> and GET /api/guide?section=<anchor> return one table-of-contents slice; the bare commands still return the whole guide. A session keeps its old MCP process after an upgrade — reconnect it (/mcp, hud status, or hud mcp reconnect for the checklist).

Coordination quickstart

hud queue                                   # ready / open / claimed work
hud claim EGO-3 --start                     # exclusive lease; moves it to doing
hud context publish --scope board:main --kind FACT --text "parser drops trailing commas"
hud context read --scope board:main         # delta reads since your cursor
hud wait --scope board:main --timeout 20    # wake on a peer publish or session end
hud attach add notes.md --scope board:main  # share a file by reference

When several agents share a board, follow one playbook:

hud guide decentralized    # everyone pulls ready work
hud guide lead             # one lead links and assigns; the others pull

See GUIDE.md and PLAYBOOKS.md.

Everyday use

Press ? for the full key map. One top bar holds the workspace picker (the API calls a workspace a board), the Tasks/Monitors toggle (l), the "needs you" badge (A), search (⌘/Ctrl+K) and the ⋯ menu. One inspector scrolls overview, activity and settings.

Learn more

• QUICKSTART.md — install, first run, updates, the board, agents.

• PRODUCT.md — the product contract: leases, reclaim, trees, and which issue serves which criterion.

• GUIDE.md — the agent and operator guide: tools, schemas, renderers, coordination, install and updates.

• STYLE.md — the dark desktop visual contract.

• AGENTS.md — architecture and contributor conventions.

• views/README.md — writing or generating chart renderer modules.

Security

hud binds to 127.0.0.1/::1, rejects foreign Host/Origin headers, and sends a strict CSP. Command monitors and apply run with your permissions, so review anything an agent asks hud to execute. Your board, backups and the single-server lock live in the per-user data directory (~/Library/Application Support/hud on macOS, %APPDATA%\hud on Windows, ~/.local/share/hud elsewhere).