# 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-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-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 `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.)
- **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.**