HOOP

HOOP provides real-time observability and control for NEEDLE worker fleets, surfacing what's stale, stuck, or missing before it becomes a problem. It reads everything—bead queues, CLI session transcripts, worker heartbeats, event logs—and presents a unified view in a web dashboard and REST/WebSocket API. It writes exactly one thing: creating new beads via `br create`. Every other mutation requires operator approval. HOOP is passive observability that creates pressure for action, not active control that acts without permission.

The real-time fleet dashboard shows all projects, beads, session transcripts, and worker health in one place. A React/Vite frontend connects via WebSocket to stream live updates—workers transitioning from Live to Hung to Dead, beads moving through claim-to-completion, sessions appearing and disappearing. No more scattered terminals or file-shelling into workspaces to see what's happening. The dashboard is the single pane of glass into fleet health, and it updates in real time.

Session tailing is where HOOP bridges the gap between worker activity and human understanding. It parses JSONL transcripts from Claude Code, Codex, OpenCode, Gemini, and Aider—linking each session to specific beads via NEEDLE's dispatch tags. When a worker claims a bead, HOOP knows which transcript to watch. When the worker completes, fails, or times out, HOOP surfaces the relevant session excerpt in the timeline. You don't just see that a bead failed; you see exactly what the worker was doing when it died.

Worker health monitoring classifies every worker into three states: Live (fresh heartbeat + PID alive), Hung (PID alive but heartbeat stale), or Dead (PID gone). The heartbeat monitor reads `.beads/heartbeats.jsonl` every 10 seconds, classifying workers based on the last-seen timestamp and process state. A worker that's spinning at 100% CPU but hasn't produced output? That's Hung. A worker that crashed with a segfault? That's Dead. A worker chugging along normally? That's Live. Three states, no ambiguity, and the dashboard shows you exactly which workers need attention.

Stuck detection prevents silent failures from consuming time and budget. Three independent timers track different failure modes: idle silence timeout (3 min default) fires when a worker produces no output, max runtime ceiling (1 h) kills runaway tasks, content-seen grace (10 min after content appears) handles workers that are making progress but slowly. When any timer fires, the worker is marked Hung and the operator is alerted. These thresholds are configurable per workspace or globally, but the defaults catch the vast majority of stuck workers without false positives.

Saturation alerting provides advance warning before quotas are exhausted. When an account hits 80% of its 5-hour or 7-day usage window, HOOP fires an alert—informational only, never throttling. The alert clears at 75% (5% hysteresis prevents flapping). This buffer gives operators time to adjust: spin down workers, switch credentials, or pause non-critical work. HOOP monitors but never interferes. The fleet keeps running; HOOP just tells you when you're approaching the edge.

The human-interface agent is HOOP's persistent LLM conversation partner for the operator. It reads everything—fleet state, bead queues, session transcripts, worker health—and writes only by proposing new stitches for approval. Want to spawn follow-up work? The agent drafts a stitch, you approve, HOOP calls `br create`. Need to investigate a pattern across multiple failures? The agent reads the transcripts, proposes hypotheses, and suggests beads to drill down. The agent is a tireless analyst that surfaces insights without ever muting state on its own.

Tamper-evident audit logging provides verifiable history for all auditable events. Every event—bead creation, worker dispatch, completion, failure, heartbeat classification—includes a SHA-256 hash of the previous entry, creating an immutable hash chain. Run `hoop audit verify` to confirm the log hasn't been tampered with. The audit trail survives daemon restarts, database migrations, and even complete fleet rebuilds. HOOP forgets nothing and proves it cryptographically.

Snapshot backups protect the fleet database against catastrophic loss. HOOP's SQLite database at `~/.hoop/fleet.db` backs up to any S3-compatible endpoint on a configurable cron schedule. Backups are encrypted at rest (optional), retain for configurable days, and restore with a single command. The backup captures everything: projects, workspaces, stitches, beads, worker states, and audit logs. Restore after a disk failure or migrate to a new machine without losing history.

MCP server integration exposes HOOP's read APIs to external LLM clients and tools. Read-only tools like `find_stitches`, `read_stitch`, `find_beads`, `read_bead`, `read_file`, `grep`, and `search_conversations` require no approval—agents can query fleet state freely. The single write tool, `create_stitch`, requires operator approval before any bead is created. Explicitly forbidden operations—launching fleets, stopping workers, mutating state—return hard errors if called. HOOP's MCP server observes and suggests, never commands.

Self-contained deployment means HOOP is a single binary that serves its own embedded web UI. No external database, no separate frontend server, no complex architecture. Install to `~/.local/bin/hoop`, run `hoop init` for first-time setup, then `hoop serve` to start the daemon at http://127.0.0.1:3000. The daemon runs as a systemd user service for auto-restart on failure. When HOOP stops, NEEDLE keeps running—workers keep writing heartbeats and events. HOOP is a convenience layer, not a dependency for worker operation.