docs(maestro): describe the single-host architecture
ci / rust (push) Successful in 2m40s

Rewrites CLAUDE.md as the current-architecture reference, drops the
registry from INSTALL/PRODUCT/DESIGN and the web README, deletes the
registry Dockerfile, and marks the dated design specs superseded where
they describe the registry, JWT auth, or cross-host attach.

The installer loses its configure step — every config field now has a
default, so a daemon starts with no config file at all.
This commit is contained in:
Miguel Palhas
2026-08-22 10:26:49 +01:00
parent de097cf17f
commit c856333e4a
25 changed files with 156 additions and 326 deletions
+12 -13
View File
@@ -7,22 +7,21 @@ product
## Users
A single technical operator (a developer) managing every interactive shell and
agent — Claude Code, opencode, plain bash — running across multiple machines.
The job-to-be-done: from any device (laptop, desktop, **phone**), get an
accurate at-a-glance picture of all live sessions across all hosts, then attach
to one and drive its terminal. Usage is often glance-and-go: checking on a
agent — Claude Code, opencode, plain bash — running on a machine. The
job-to-be-done: from any device (laptop, desktop, **phone**), get an accurate
at-a-glance picture of all live sessions on that host, then attach to one and
drive its terminal. Usage is often glance-and-go: checking on a
long-running agent, killing a stray session, or hopping into a shell mid-task.
Mobile-first is a hard requirement — touch targets, viewport-fit safe areas,
and bottom-sheet modals already reflect this.
## Product Purpose
Maestro is a unified terminal-session orchestrator: one place to see and attach
to every interactive session running across every machine the operator cares
about. tmux for persistence, WebSocket for transport, a daemon-per-host
federated by a small always-on registry. The web UI is the browser face of
that system — it renders the cross-host session catalog and provides the attach
terminal (xterm.js). Success = the operator trusts the picture is accurate and
Maestro is a terminal-session orchestrator: one place to see and attach to
every interactive session running on a machine. tmux for persistence,
WebSocket for transport, one daemon per host. The web UI is the browser face of
that system — it renders the session catalog and provides the attach terminal
(xterm.js). Success = the operator trusts the picture is accurate and
current, and can get from "open the page" to "typing in the right session" in
seconds, on any device.
@@ -51,14 +50,14 @@ efficient, calm / uncluttered, with earned moments of delight.
## Design Principles
1. **The scan is the product.** Optimize for instant comprehension of "what's
running, where, and is it healthy" across many sessions and hosts. Status
legibility beats everything else.
running, where, and is it healthy" across many sessions. Status legibility
beats everything else.
2. **Calm under load.** Stay uncluttered whether there are 3 sessions or 300;
hierarchy and grouping carry the weight, not color-shouting every row.
3. **Fast and keyboard-literate.** Low-friction, efficient, gets out of the
way; honor keyboard navigation, don't make the operator hunt.
4. **Monospace as identity.** Treat the mono/sans pairing as deliberate brand
typography, not just terminal output. Ids, hosts, counts, and state read as
typography, not just terminal output. Ids, paths, counts, and state read as
precise technical data.
5. **Earned delight.** Personality lives in motion and micro-detail (live-status
pulse, attach transitions, cursor cues), never in noise — always craft.