naps62-yolo
278c81d2bc
- `RunConfig` grows a `config_path: Option<PathBuf>` field, plumbed from the umbrella binary's global `--config` flag through to `MaestroConfigFile` loading. Explicit `--config <path>` wins over `$MAESTRO_CONFIG` over the platform default; a missing file still falls back to shipped defaults. - `docs/INSTALL.md` gains a "terminal UI" section: that `maestro tui` ships in the default feature set, how to opt out (`--no-default-features --features cli,daemon`), the `MAESTRO_DAEMON_URL` override, and a worked example of `[tui]` / `[tui.keymap.normal]` config pointing at the full action vocabulary in the design spec. - Adds a thin-build line for `--features cli` (CLI-only client) and lists `tui` in the default-feature set. - CLAUDE.md repo-layout block lists the new `maestro-tui` crate. Closes the NAP-275 v1 epic.
3.0 KiB
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.
Where the spec lives
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.
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.
.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.
crates/
├── maestro/ # umbrella binary `maestro` (cli + daemon + registry, feature-gated) (NAP-245)
├── maestro-protocol/ # shared wire types (NAP-211)
├── maestro-config/ # shared on-disk config schema (NAP-233)
├── 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-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)
└── maestro-e2e/ # cross-process integration tests (NAP-217)
web/ # browser SPA (NAP-218)
See docs/INSTALL.md for end-user install instructions.
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
maestroscope. Example:feat(maestro): add Hello message round-trip test. cargo fmt+cargo clippy --all-targets -- -D warningsbefore every commit. (Add to CI as part of NAP-211.)- Integration tests use real
tmuxandgit. Don't mock them. Isolate via temp$HOMEandTMUX_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.