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
@@ -1,33 +1,57 @@
|
||||
# Maestro
|
||||
|
||||
A unified terminal-session orchestrator. One place — laptop, desktop, or phone — to see and attach to every interactive shell or agent (Claude Code, opencode, plain bash) running across every machine you care about. tmux for persistence, WebSocket for transport, daemon-per-host federated by a small always-on registry.
|
||||
A terminal-session orchestrator for one machine. One daemon per host owns every
|
||||
interactive shell or agent (Claude Code, opencode, plain bash) running on it;
|
||||
clients — CLI, TUI, browser — attach over a plain HTTP + WebSocket API. tmux for
|
||||
persistence, WebSocket for transport.
|
||||
|
||||
## Where the spec lives
|
||||
## Architecture
|
||||
|
||||
`docs/superpowers/specs/2026-05-24-maestro-design.md` is the source of truth for architecture, wire protocol, session model, auth, repo layout, and scope boundary. **Read it before writing any code in this repo.**
|
||||
```
|
||||
maestro daemon tmux wrapper + session API on 127.0.0.1:7070
|
||||
├── GET/POST /api/sessions list / spawn
|
||||
├── DELETE /api/sessions/:id kill
|
||||
├── GET /api/info hostname, version, home dir, spawn presets
|
||||
├── GET /api/dirs directory listing (spawn autocomplete)
|
||||
├── GET /api/recent-dirs spawn history
|
||||
├── GET /api/gitroot enclosing repo of a path
|
||||
├── WS /api/events Snapshot + session deltas
|
||||
└── WS /api/attach/:id raw PTY bytes
|
||||
|
||||
maestro list/spawn/attach/kill CLI client
|
||||
maestro tui ratatui client
|
||||
maestro-web serves the SPA, reverse-proxies /api/* to the daemon
|
||||
```
|
||||
|
||||
**No authentication layer, no registry, no peer-to-peer.** Whoever can reach the
|
||||
daemon's bind address can drive every session on the host — same trust model as
|
||||
tmux itself. The operator picks the perimeter: `127.0.0.1` for local-only, a
|
||||
WireGuard/LAN address to share with their own devices, never a public IP.
|
||||
|
||||
Every config field has a default, so `~/.config/maestro/config.toml` is
|
||||
optional.
|
||||
|
||||
## Where the work is
|
||||
|
||||
Linear project **Maestro** under team **Naps62**. Issues `NAP-211..218` cover the prototype; each has `blockedBy` set so the dependency chain is explicit. **`NAP-211` is the only unblocked starting point.**
|
||||
Linear project **Maestro** under team **Naps62**.
|
||||
|
||||
`.claude/linear.json` wires `/yolo` and `/work` to this project — they pick from "available now" (status backlog/pending, not blocked).
|
||||
`.claude/linear.json` wires `/yolo` and `/work` to this project — they pick from
|
||||
"available now" (status backlog/pending, not blocked).
|
||||
|
||||
## Repo layout
|
||||
|
||||
Cargo workspace. NAP-245 unified the per-binary crates behind a single
|
||||
`crates/maestro/` umbrella that ships the `maestro` binary with feature gates
|
||||
(`cli` / `daemon` / `registry`, default = all three). The library crates kept
|
||||
their existing shape; only the per-binary `main.rs` files were retired.
|
||||
(`cli` / `daemon` / `tui`, default = all three).
|
||||
|
||||
```
|
||||
crates/
|
||||
├── maestro/ # umbrella binary `maestro` (cli + daemon + registry, feature-gated) (NAP-245)
|
||||
├── maestro/ # umbrella binary `maestro` (cli + daemon + tui, feature-gated) (NAP-245)
|
||||
├── maestro-protocol/ # shared wire types (NAP-211)
|
||||
├── maestro-config/ # shared on-disk config schema (NAP-233)
|
||||
├── maestro-names/ # orchestra-themed session-handle generator (#23)
|
||||
├── maestro-cli/ # `maestro list/spawn/attach/kill/policy` dispatch (NAP-216)
|
||||
├── maestro-daemon/ # `maestro daemon` — tmux wrapper + WS endpoints (NAP-212, NAP-214)
|
||||
├── maestro-registry/ # `maestro registry` — phone book + HTTP API (NAP-213, NAP-215)
|
||||
├── maestro-cli/ # `maestro list/spawn/attach/kill` dispatch (NAP-216)
|
||||
├── maestro-daemon/ # `maestro daemon` — tmux wrapper + HTTP/WS API (NAP-212, NAP-214)
|
||||
├── maestro-web/ # standalone `maestro-web` browser UI (NAP-241, NAP-249)
|
||||
├── maestro-tui/ # `maestro tui` — ratatui session manager (NAP-275 epic)
|
||||
├── maestro-installer/ # `maestro-install` wizard: cargo install + systemd (NAP-225)
|
||||
@@ -37,18 +61,13 @@ web/ # browser SPA (NAP-218)
|
||||
|
||||
See `docs/INSTALL.md` for end-user install instructions.
|
||||
|
||||
The dated design docs under `docs/superpowers/specs/` predate the single-host
|
||||
refactor; they carry banners marking what no longer applies.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **TDD by default.** Failing test first, then minimal impl. Commit test + impl together.
|
||||
- **Frequent commits.** One logical unit per commit; don't pile work up.
|
||||
- **Conventional commits with `maestro` scope.** Example: `feat(maestro): add Hello message round-trip test`.
|
||||
- **`cargo fmt` + `cargo clippy --all-targets -- -D warnings`** before every commit. (Add to CI as part of NAP-211.)
|
||||
- **`cargo fmt` + `cargo clippy --all-targets -- -D warnings`** before every commit.
|
||||
- **Integration tests use real `tmux` and `git`.** Don't mock them. Isolate via temp `$HOME` and `TMUX_TMPDIR`.
|
||||
|
||||
## Network assumption
|
||||
|
||||
Maestro is network-agnostic. The operator chooses bind addresses; the perimeter is whatever VPN (Wireguard, etc.) or private LAN they've set up. Maestro does not terminate TLS itself or police the network. See spec §Auth.
|
||||
|
||||
## Status
|
||||
|
||||
Empty repo. Spec approved and committed. **NAP-211 is the natural start.**
|
||||
|
||||
Reference in New Issue
Block a user