Product

Platform

web

Users

One operator who runs agent swarms. He keeps a ledger page open for hours on a 1920x1080 screen while Claude and Codex agents work a plan. From it he follows progress, answers agent questions, checks phases, writes notes and comments, gives verdicts on health findings, steers the swarm (start, pause, stop, caps, gates, autonomy) and chats with the swarm master. Agents never read the page visually: they write to the same ledger through the agentihooks ledger and agentihooks swarm CLIs and the ledger server API.

Product Purpose

The ledger front end is the presentation layer of agentihooks. Since 2026-10-06 the operator treats it as a product in its own right rather than a skill’s by-product. It shows one plan’s record (overview, sources, phases, tasks with proof contracts, questions, follow-ups, notes, artifacts, chat, notifications) and the live swarm working it (agents, lanes, quota, gates, health, Doctor). HOME lists every ledger and BIN holds deleted ones for 30 days. Success means the operator sees what needs him at a glance and acts in one click, without opening a terminal.

Positioning

It is the only window onto an agentihooks swarm, and its records are the swarm’s own: every operator write on the page becomes an inbox item for the agent that owns the task, and every agent write shows on the page without a refresh. Generic project boards show tickets; this page shows the agents doing the work, their quota and their proof.

Operating Context

  • Served on localhost by the ledger server (agentihooks ledger serve --ensure, default http://127.0.0.1:8765), Python stdlib only, no build step. Viewed in desktop Chrome on Windows from WSL.
  • Ledger state lives in one SQLite database, ~/development-ledger/ledgers.sqlite3, behind the ledger repository; a write touches only the rows it changed and no JSON or HTML file. The page shell carries no seed: it loads its state from the event stream and saves through the server API. JSON stays an explicit interchange format (agentihooks ledger storage export and import).
  • The swarm tick, inbox and health data come from Redis through the same server.
  • Agents and the operator act on the same records concurrently, often dozens of writes a minute in a busy swarm.

Capabilities and Constraints

  • Stack (operator decision): plain HTML, CSS and vanilla JavaScript only. No frameworks, bundlers or build step (no React, Next or similar).
  • Architecture (delivered): the presentation layer has its own architecture: versioned v1 resources, an event stream, static page shells and SQLite as the durable store in place of per-ledger JSON files. Legacy ledger files are imported once after a verified backup.
  • Front-end sources: scripts/swarm_ledger/shell.html and scripts/swarm_ledger/static/ (ledger page), scripts/swarm_ledger/home.html (HOME and BIN), palette.css (every colour value, nowhere else), tooltips.js. The server fills __LEDGER_*__ / __HOME_*__ placeholders at render time.
  • Only the Ledger tab’s sections below Overview, the Swarm tab panels below Capacity, the outline categories and comment dropdowns fold, each remembering its choice per viewer; nothing else folds (chat and side windows, Stats, Overview, the Swarm control bar and Capacity, HOME, BIN), and a fold anywhere else fails its test.
  • Every column resizes by dragging its header edge (every ledger page table, the HOME and BIN columns), with the widths saved in the shared page layout beside the panel sizes; a column the grips cannot reach fails its test.
  • A page edit changes the page version (hash of the shell, the HOME page and every static asset), and open ledger pages load the new assets on their next load.
  • Vocabulary: ledger, phase, task, proof, follow-up, question, note, seat, lane (eng, ci, plan), master, swarm tick, gate, health finding, verdict, Doctor, inbox, BIN.

Brand Commitments

  • Name: agentihooks, set in lowercase in the brand mark and uppercase in the HOME header.
  • Logo: media/agentihooks-logo.png, used as a mask in the header and as the HOME watermark.
  • Design system 2026-001 (operator’s design-system base) governs structure. Operator overrides for this product: no text glow, and a near-black canvas without the blue wash.

Evidence on Hand

  • Live ledgers in ~/development-ledger (for example rig-grade-swarm, 287 tasks) are the real content to design against.
  • No user research, analytics or external users exist. Do not invent them.

Product Principles

  1. The operator steers and the agents write. Every screen answers “what needs me now?” before anything else.
  2. State over decoration. Colour and type carry status; nothing decorative competes with a state change.
  3. One source of truth. The page renders the ledger record; it never holds state the server does not.
  4. Minimal stack. HTML, CSS and vanilla JS served by the ledger server; a new dependency needs the operator’s decision.
  5. Fit a working day. The page stays readable and calm after hours open, with dense data at 1920x1080.

Accessibility & Inclusion

Keyboard reachable controls with a visible focus-visible ring, and text contrast held against the canvas for every role colour. No further standard has been set.