hud

A local Linear plus monitoring, on a live canvas shared by you and any agent: tickets with projects, KEY-n idents, sub-tickets and dependencies, and monitors that watch commands, HTTP endpoints, ports, certificates, cron heartbeats and anything a probe can reach. Black and white, terminal-style. The server has no runtime dependencies; Node ≥ 23.6 runs the TypeScript directly.

node bin/hud.js open        # start the server (if needed) and open http://localhost:7317

Hook up agents

hud mcp install          # wire into claude + codex + opencode
hud mcp status           # show where hud is configured
hud mcp uninstall        # remove it again
hud mcp print generic    # snippet for any other client

From the repo, prefix with node bin/hud.js, or npm link to put hud on PATH. Each command only touches the hud entry and backs the config up first. To have monitor alerts wake a Claude Code session, start it with claude --dangerously-load-development-channels server:hud, then have the agent hud_watch the monitors it owns.

Agents get hud_overview, hud_tickets, hud_create, hud_update, hud_push, hud_comment, … (full list in GUIDE.md, also served at GET /api/guide and by hud guide). The MCP server and CLI start the hud server on demand. Anything with a shell can use the hud CLI or plain HTTP.

Related MCP server: viqueue

Tickets (local Linear)

• A project owns a KEY (EGO) that gives its tickets idents (EGO-3) and git branch names. Anything that takes an id takes an ident.

• parent makes sub-tickets, blockedBy is the dependency edge (a ticket waiting on open blockers blocks itself and clears itself), refs are loose links; cycles are rejected.

• Statuses backlog todo doing review blocked done canceled, priorities low med high urgent (case-insensitive, common aliases accepted). An agent that needs a human to choose proposes decision options on a ticket; the human clicks one on the card and the agent is woken with the answer (red = waiting, green = done).

• Read it as a canvas card, or press l for the list view; hud ls tickets prints the same on the command line.

Monitors

Value, state, message, progress. Fed by hand, by pushes from outside processes, polled by hud via a shell command, an http check or a TypeScript probe (built in: tcp, tls, dns, disk, file-age; examples: git, process, tail), or reported by a cron job through a heartbeat URL. Thresholds, staleness, 24 h history with uptime, and alerts. There are 19 views (number, progress, line, bar, pie, histogram, heatmap, 3-D, …), and auto picks from the data shape; press v to cycle by hand, or write your own renderer in views/.

curl -fsS localhost:7317/ping/nightly-backup?period=86400      # heartbeat: no ping in period+grace is an error
hud add monitor "api" --source.kind http --source.url https://example.com/health --source.contains ok
hud push etl --progress 40 --message "batch 4/10"                # creates the monitor on first push

import { Hud } from './src/client.ts';
await new Hud({ actor: 'etl' }).push('etl', { progress: 40, message: 'batch 4/10' });

Notes are markdown with - [ ] checkboxes, frames are labelled regions that carry what is inside, utilities are on-canvas tools (timer, calculator, sheet, …). Boards are separate canvases (the tabs at the top).

CLI cheatsheet

hud ls [board] · hud ls tickets [--status s,s --assignee a --project KEY --tag t --overdue]
hud find <text> · hud show <id> · hud log <id>
hud add ticket "title" --project EGO --blockedBy EGO-2 · hud set <id> --status doing · hud link <id> parent=EGO-1
hud comment <id> <text> · hud ask <id> --option A --option B · hud decide <id> <optionId>
hud push <id> 42 · hud ping <id> [start|fail|<code>] · hud run <id> · hud finish
hud rm <id> · hud trash · hud restore <id> · hud purge <id>|--all
hud backup [--list] · hud export [file] · hud import <file> [--merge]
hud status · hud start|stop|open · hud guide

Every command takes --help and --json. Nothing is deleted outright: rm moves to the trash, state is backed up hourly and before risky operations, and a corrupt state file is recovered from the newest backup.

Keys

Press ? in the app. In short: double-click a card to expand it in place, double-click empty space to add, drag to pan, ⌘/ctrl+scroll to zoom, t m n f w to create (ticket, monitor, note, frame, widget), ⏎ to open the drawer, l for the list view, v to cycle a monitor's view, ⌫ to delete, u or ⌘/ctrl+Z to undo, : for the command line, a for the activity feed.

Standalone app

A real desktop window (Electron), one build per OS, no Node install needed to run it. The app binary is also the CLI and the MCP server, so hud mcp install and the CLI shim point at the same file.

npm install
npm run dev          # run the app from source on a scratch port + scratch data dir
npm run pack         # unpacked app in dist/ (fast smoke test)
npm run dist         # installers: .dmg, .exe (NSIS), .AppImage/.deb
npm run dist:mac     # or dist:win / dist:linux

Each OS builds its own artifact. A packaged app keeps its data under the per-user dir (~/Library/Application Support/hud on macOS, %APPDATA%\hud on Windows, ~/.local/share/hud elsewhere), seeds the example probes and views there on first run, and closes to the tray with the server still up so agents keep working. Help → Install "hud" command… puts hud on your PATH. There is no auto-updater: install a new build to update.

Builds are not signed or notarized (no Developer ID, no entitlements file). macOS Gatekeeper will warn on first launch; right-click → Open, or sign the build yourself. Command monitors and the alert hook need a POSIX shell, so those are macOS/Linux features; the tail and process probes are POSIX only too.

Files

src/server.ts HTTP + SSE + static · src/store.ts state, persistence, backups, trash · src/lock.ts one server per data dir · src/engine.ts monitor runner · src/mcp.ts MCP stdio server · src/mcpinstall.ts agent wiring · src/cli.ts CLI · src/cliinstall.ts the hud command shim · src/client.ts TS client · src/summary.ts text overview · src/types.ts data model · src/config.ts, src/assets.ts, src/electron-runtime.ts paths and entry points · electron/main.ts the desktop shell · web/ UI (app.js, views.js charts, utils.js) · views/ renderer modules · probes/ probe modules · scripts/ build, dev and icon scripts · your data lives in the per-user dir (~/Library/Application Support/hud on macOS): state.json, backups/, server.log.

Env: the port (7317) and data dir (per-user) are fixed: one board, one server. HUD_PORT, HUD_DATA, HUD_PROBES, HUD_VIEWS and HUD_URL are ignored unless HUD_SCRATCH=1 (throwaway test instances only). HUD_ACTOR (name shown on changes), HUD_SESSION (alert session name), HUD_TIMEOUT / HUD_MCP_TIMEOUT (ms), HUD_ALERT_CMD (shell hook; alert JSON on stdin), HUD_BIN_DIR (where hud cli install writes), HUD_TRAY=0 (no tray icon). Internal/dev: HUD_SOURCE_ROOT, HUD_CLI_ENTRY, HUD_SHIM, HUD_NO_LOGIN_SHELL, HUD_DEV_PORT, HUD_DEV_DATA.

Security: binds to 127.0.0.1/::1 only, rejects foreign Host/Origin headers (command monitors run shell commands, so no web page can reach the API), and sends a strict CSP.