maestro/CLAUDE.md

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 (target)

Cargo workspace, populated incrementally starting with NAP-211:

crates/
├── maestro-protocol/    # shared wire types (NAP-211)
├── maestro-daemon/      # per-host tmux wrapper + WS endpoints (NAP-212, NAP-214)
├── maestro-registry/    # always-on phone book + HTTP API (NAP-213, NAP-215)
├── maestro-cli/         # `maestro list/spawn/attach/kill` (NAP-216)
├── maestro-installer/   # `maestro-install` wizard: cargo install + systemd (NAP-225)
└── maestro-e2e/         # cross-process integration tests (NAP-217)
web/                     # browser client (NAP-218, plan 2)

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.