maestro-tui 0.1.0__tar.gz

maestro_tui-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+
+# Publishes to PyPI when you push a version tag (e.g. v0.1.0).
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored in the repo.
+# One-time setup on PyPI: project Settings → Publishing → add a GitHub
+# trusted publisher with owner=jmbmunda, repo=maestro, workflow=release.yml,
+# environment=pypi.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

maestro_tui-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.maestro/
+dist/
+build/
+*.egg-info/

maestro_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Mark Munda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maestro_tui-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: maestro-tui
+Version: 0.1.0
+Summary: A terminal-native multi-agent command center
+Project-URL: Homepage, https://github.com/jmbmunda/maestro
+Project-URL: Repository, https://github.com/jmbmunda/maestro
+Project-URL: Issues, https://github.com/jmbmunda/maestro/issues
+Author-email: Jay Mark Munda <jbmunda@multisyscorp.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,orchestration,terminal,textual,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: ptyprocess>=0.7.0
+Requires-Dist: pyte>=0.8.2
+Requires-Dist: textual>=0.86.0
+Requires-Dist: tomli-w>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# maestro
+
+A terminal-native multi-agent command center. Spawns AI/CLI agents in real PTYs
+and shows them in switchable panes with a session timeline — all inside one TUI.
+
+## Install
+
+Maestro is a Python CLI (needs **Python 3.11+** and a `claude` on your PATH).
+Install it on any device with [`pipx`](https://pipx.pypa.io) so it lands in its
+own isolated venv with the `maestro` command on your PATH:
+
+```bash
+pipx install "git+https://github.com/jmbmunda/maestro.git"
+```
+
+Or run it once without installing, using [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/jmbmunda/maestro.git maestro
+```
+
+Update later with `pipx upgrade maestro`. Pin a release with `...@v0.1.0`.
+
+### From source (development)
+
+```bash
+git clone https://github.com/jmbmunda/maestro.git && cd maestro
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+```bash
+maestro
+```
+
+## Keys
+
+Each pane is a **real terminal** (full ANSI: colors, cursor, alt-screen), so
+`claude`, `vim`, `htop` etc. render correctly. Maestro has two modes:
+
+**OUTSIDE** (default — manage panes):
+
+- `Ctrl+S` — spawn a `claude` agent in a new pane
+- `Ctrl+Shift+S` — spawn a `$SHELL` agent (terminal-dependent; see note)
+- `Ctrl+W` — dismiss the focused pane (confirms first if it's still running)
+- `r` — rename the focused pane (blank resets to the default `pane-N · claude`)
+- `b` — broadcast one prompt to multiple panes at once (pick targets, type, Enter)
+- `a` — quick agents: launch a pre-seeded role, or create/edit/delete templates
+- `Ctrl+J` / `Ctrl+K` — focus next / previous pane
+- `Ctrl+L` — cycle layout: split → grid → focused
+- `Ctrl+B` — toggle the sessions status panel
+- `Ctrl+T` — toggle the timeline
+- `/` — open the **skills launcher** (pick a skill → injects `/name` into the focused pane)
+- `Enter` — step **INSIDE** the focused pane to interact with it
+- `q` — quit (also `Ctrl+Q`, where the terminal doesn't grab it — the VSCode
+  integrated terminal does)
+
+**INSIDE** (drive one agent): every keystroke goes straight to that pane's
+terminal — arrows, `Esc`, `Tab`, `Ctrl-C`, everything. The one reserved key is
+**`Ctrl+Esc`**, which steps back OUTSIDE.
+
+> **Heads-up:** `Ctrl+Esc` only fires in terminals that transmit it distinctly
+> (kitty keyboard protocol / `modifyOtherKeys=2`). If your terminal doesn't, the
+> binding won't trigger and there's no built-in fallback exit — kill maestro from
+> another terminal (`pkill -f maestro`) and report it so we can add a fallback. The footer reflects the mode — while INSIDE
+it shows just `Ctrl+] Exit pane`; OUTSIDE it shows the command list.
+
+**Click a pane to focus + interact in one step** — clicking auto-enters that pane,
+no separate `Enter` needed. Clicking a different pane while INSIDE another stays
+INSIDE the new one. Clicking a finished pane drops you back OUTSIDE. In **focused**
+layout, click a row in the `panes` strip to switch.
+
+(Keyboard nav `Ctrl+J`/`Ctrl+K` still moves focus *without* auto-entering, so you
+can chain commands like spawn → navigate → spawn → … without stepping in.) The background is transparent, so maestro inherits your terminal's
+wallpaper/theme.
+
+### Quick agents
+
+Press **`a`** (OUTSIDE) for one-click specialized agents. A quick agent is a template
+— a name + a starting prompt + an optional skill — that spawns a `claude` pane, names
+it, injects the skill and prompt, and drops you inside. Ships with built-ins (Reviewer,
+Tester, Security, Docs, Refactor) and is fully CRUD-able in-app: **Enter** launches the
+highlighted one, **n** new, **e** edit, **d** delete. Templates live in a hand-editable
+`~/.config/maestro/quick-agents.toml` (seeded on first run).
+
+### Broadcast
+
+Press **`b`** (OUTSIDE) to fan one prompt out to several sessions at once: a modal
+lists the running panes (all checked by default — Space toggles), you type a prompt,
+and Enter sends it to every checked pane. Great for "run the same task across N
+agents" or kicking off a fleet. Uncheck any pane (e.g. a `$SHELL`) you don't want.
+
+### Skills
+
+Press **`/`** (OUTSIDE) to open the skills launcher — a filterable list of the skills
+in `~/.claude/skills` (and a project's `.claude/skills`). Pick one and maestro types
+`/name` into the focused pane and steps you inside, exactly as if you'd typed it in
+Claude. (Typing `/name` yourself while INSIDE still works too.)
+
+Maestro also watches each pane's output for Claude's skill markers and shows the
+active skill as a `⚡<skill>` badge on the pane's border (best-effort — it keys off
+Claude's output text).
+
+### Status board
+
+Maestro shows, at a glance, which sessions need you. Each pane gets a best-effort
+status inferred from output timing:
+
+- `▶` **working** — producing output right now
+- `⏳` **waiting** — alive but quiet → *needs you* (a question, an approval, or just
+  done with its turn); the pane border glows amber
+- `○` **done** — exited cleanly · `✗` **failed** — exited non-zero
+
+There's a dedicated **`sessions`** panel at the top listing every pane with its
+status, the header summarises it (e.g. `maestro   ▶2 ⏳1 ○1`), and each pane border
+reflects it too. (Heuristic: maestro can't tell "waiting for approval" from "waiting
+for your next message" — both show as `⏳ waiting`.) The focused pane stands out with a
+**colored border** (green while you're INSIDE it) and full-brightness text, while
+non-focused panes are dimmed. The `sessions` panel is **on by default** (toggle with
+`Ctrl+B`); the `timeline` event log is **off by default** (toggle with `Ctrl+T`).
+
+### Theme
+
+Maestro defaults to the **`ansi-dark`** theme, which draws with your terminal's own
+16-colour palette — so it adapts to whatever colour scheme your terminal uses. Press
+`Ctrl+P` → "Change theme" to pick another (`ansi-light` for light terminals, or any
+of Textual's built-ins like `gruvbox` / `dracula`). Your choice is remembered in
+`.maestro/state.json`.
+
+> **Note:** `Ctrl+Shift+S` relies on the terminal forwarding shift+ctrl combos; some
+> terminals fold it into `Ctrl+S`. `claude` is the default spawn either way.
+>
+> `Ctrl+]` is the only key maestro reserves while INSIDE, so apps that use it
+> (e.g. vim's tag-jump) won't see it.
+
+## Layouts
+
+- **split** — vertical stack; auto-promotes to grid once a 4th pane spawns
+- **grid** — auto-shaped tiles (2×2, 2×3, 3×3, then a scrollable 3×N)
+- **focused** — one large pane plus a left strip of status tiles for the rest
+
+When an agent **exits cleanly** (`exit=0`) the pane is auto-dismissed — no
+frozen-screen confusion. **Failed exits** (non-zero) stay sticky so you can read
+what went wrong; press `Ctrl+W` to dismiss those.
+
+## Layout
+
+```
+┌─timeline──────────────────────────────────────────┐
+│ 16:18:30 spawn  pane-1 claude                      │
+│ 16:18:42 spawn  pane-2 /bin/zsh -l                 │
+└────────────────────────────────────────────────────┘
+┌─panes──┐ ┌─● pane-1 · claude · INSIDE — Ctrl+Esc to exit┐
+│ ● 1 cla│ │                                            │
+│ ○ 2 sh │ │   (live terminal — claude renders here)    │
+│ ◄      │ │                                            │
+└────────┘ └────────────────────────────────────────────┘
+```
+
+(The `panes` strip only appears in **focused** layout. A pane's border turns
+heavy/green while you're INSIDE it.)
+
+## Where things live
+
+- `maestro/app.py` — Textual app, key bindings, focus-toggle, spawn/dismiss/focus
+- `maestro/panes.py` — `Pane` model + `PaneManager` state machine (Textual-agnostic)
+- `maestro/layouts.py` — split / grid / focused renderers + the focus tiles strip
+- `maestro/terminal.py` — pyte-backed `Emulator`, `TerminalView`, query responder, key encoder
+- `maestro/agent.py` — PTY-backed subprocess wrapper (`ptyprocess`); raw bytes + resize
+- `maestro/events.py` — append-only JSONL event log (`.maestro/session.jsonl`)
+
+`.maestro/state.json` persists your layout + timeline-visibility choices across
+restarts. Agent sessions themselves are not resumed.
+
+## Tests
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## Next steps
+
+- Provider adapters beyond `claude` / `$SHELL` (`codex`, `gemini`, `gh copilot`)
+- Claude Code skill passthrough (toggle `~/.claude/skills` per pane)
+- Prompt library + per-agent system prompts
+- Inter-agent message bus for "review on modify" workflows
+- Terminal niceties: mouse reporting, bracketed paste, configurable INSIDE-exit key

maestro_tui-0.1.0/README.md

@@ -0,0 +1,190 @@
+# maestro
+
+A terminal-native multi-agent command center. Spawns AI/CLI agents in real PTYs
+and shows them in switchable panes with a session timeline — all inside one TUI.
+
+## Install
+
+Maestro is a Python CLI (needs **Python 3.11+** and a `claude` on your PATH).
+Install it on any device with [`pipx`](https://pipx.pypa.io) so it lands in its
+own isolated venv with the `maestro` command on your PATH:
+
+```bash
+pipx install "git+https://github.com/jmbmunda/maestro.git"
+```
+
+Or run it once without installing, using [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/jmbmunda/maestro.git maestro
+```
+
+Update later with `pipx upgrade maestro`. Pin a release with `...@v0.1.0`.
+
+### From source (development)
+
+```bash
+git clone https://github.com/jmbmunda/maestro.git && cd maestro
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+## Run
+
+```bash
+maestro
+```
+
+## Keys
+
+Each pane is a **real terminal** (full ANSI: colors, cursor, alt-screen), so
+`claude`, `vim`, `htop` etc. render correctly. Maestro has two modes:
+
+**OUTSIDE** (default — manage panes):
+
+- `Ctrl+S` — spawn a `claude` agent in a new pane
+- `Ctrl+Shift+S` — spawn a `$SHELL` agent (terminal-dependent; see note)
+- `Ctrl+W` — dismiss the focused pane (confirms first if it's still running)
+- `r` — rename the focused pane (blank resets to the default `pane-N · claude`)
+- `b` — broadcast one prompt to multiple panes at once (pick targets, type, Enter)
+- `a` — quick agents: launch a pre-seeded role, or create/edit/delete templates
+- `Ctrl+J` / `Ctrl+K` — focus next / previous pane
+- `Ctrl+L` — cycle layout: split → grid → focused
+- `Ctrl+B` — toggle the sessions status panel
+- `Ctrl+T` — toggle the timeline
+- `/` — open the **skills launcher** (pick a skill → injects `/name` into the focused pane)
+- `Enter` — step **INSIDE** the focused pane to interact with it
+- `q` — quit (also `Ctrl+Q`, where the terminal doesn't grab it — the VSCode
+  integrated terminal does)
+
+**INSIDE** (drive one agent): every keystroke goes straight to that pane's
+terminal — arrows, `Esc`, `Tab`, `Ctrl-C`, everything. The one reserved key is
+**`Ctrl+Esc`**, which steps back OUTSIDE.
+
+> **Heads-up:** `Ctrl+Esc` only fires in terminals that transmit it distinctly
+> (kitty keyboard protocol / `modifyOtherKeys=2`). If your terminal doesn't, the
+> binding won't trigger and there's no built-in fallback exit — kill maestro from
+> another terminal (`pkill -f maestro`) and report it so we can add a fallback. The footer reflects the mode — while INSIDE
+it shows just `Ctrl+] Exit pane`; OUTSIDE it shows the command list.
+
+**Click a pane to focus + interact in one step** — clicking auto-enters that pane,
+no separate `Enter` needed. Clicking a different pane while INSIDE another stays
+INSIDE the new one. Clicking a finished pane drops you back OUTSIDE. In **focused**
+layout, click a row in the `panes` strip to switch.
+
+(Keyboard nav `Ctrl+J`/`Ctrl+K` still moves focus *without* auto-entering, so you
+can chain commands like spawn → navigate → spawn → … without stepping in.) The background is transparent, so maestro inherits your terminal's
+wallpaper/theme.
+
+### Quick agents
+
+Press **`a`** (OUTSIDE) for one-click specialized agents. A quick agent is a template
+— a name + a starting prompt + an optional skill — that spawns a `claude` pane, names
+it, injects the skill and prompt, and drops you inside. Ships with built-ins (Reviewer,
+Tester, Security, Docs, Refactor) and is fully CRUD-able in-app: **Enter** launches the
+highlighted one, **n** new, **e** edit, **d** delete. Templates live in a hand-editable
+`~/.config/maestro/quick-agents.toml` (seeded on first run).
+
+### Broadcast
+
+Press **`b`** (OUTSIDE) to fan one prompt out to several sessions at once: a modal
+lists the running panes (all checked by default — Space toggles), you type a prompt,
+and Enter sends it to every checked pane. Great for "run the same task across N
+agents" or kicking off a fleet. Uncheck any pane (e.g. a `$SHELL`) you don't want.
+
+### Skills
+
+Press **`/`** (OUTSIDE) to open the skills launcher — a filterable list of the skills
+in `~/.claude/skills` (and a project's `.claude/skills`). Pick one and maestro types
+`/name` into the focused pane and steps you inside, exactly as if you'd typed it in
+Claude. (Typing `/name` yourself while INSIDE still works too.)
+
+Maestro also watches each pane's output for Claude's skill markers and shows the
+active skill as a `⚡<skill>` badge on the pane's border (best-effort — it keys off
+Claude's output text).
+
+### Status board
+
+Maestro shows, at a glance, which sessions need you. Each pane gets a best-effort
+status inferred from output timing:
+
+- `▶` **working** — producing output right now
+- `⏳` **waiting** — alive but quiet → *needs you* (a question, an approval, or just
+  done with its turn); the pane border glows amber
+- `○` **done** — exited cleanly · `✗` **failed** — exited non-zero
+
+There's a dedicated **`sessions`** panel at the top listing every pane with its
+status, the header summarises it (e.g. `maestro   ▶2 ⏳1 ○1`), and each pane border
+reflects it too. (Heuristic: maestro can't tell "waiting for approval" from "waiting
+for your next message" — both show as `⏳ waiting`.) The focused pane stands out with a
+**colored border** (green while you're INSIDE it) and full-brightness text, while
+non-focused panes are dimmed. The `sessions` panel is **on by default** (toggle with
+`Ctrl+B`); the `timeline` event log is **off by default** (toggle with `Ctrl+T`).
+
+### Theme
+
+Maestro defaults to the **`ansi-dark`** theme, which draws with your terminal's own
+16-colour palette — so it adapts to whatever colour scheme your terminal uses. Press
+`Ctrl+P` → "Change theme" to pick another (`ansi-light` for light terminals, or any
+of Textual's built-ins like `gruvbox` / `dracula`). Your choice is remembered in
+`.maestro/state.json`.
+
+> **Note:** `Ctrl+Shift+S` relies on the terminal forwarding shift+ctrl combos; some
+> terminals fold it into `Ctrl+S`. `claude` is the default spawn either way.
+>
+> `Ctrl+]` is the only key maestro reserves while INSIDE, so apps that use it
+> (e.g. vim's tag-jump) won't see it.
+
+## Layouts
+
+- **split** — vertical stack; auto-promotes to grid once a 4th pane spawns
+- **grid** — auto-shaped tiles (2×2, 2×3, 3×3, then a scrollable 3×N)
+- **focused** — one large pane plus a left strip of status tiles for the rest
+
+When an agent **exits cleanly** (`exit=0`) the pane is auto-dismissed — no
+frozen-screen confusion. **Failed exits** (non-zero) stay sticky so you can read
+what went wrong; press `Ctrl+W` to dismiss those.
+
+## Layout
+
+```
+┌─timeline──────────────────────────────────────────┐
+│ 16:18:30 spawn  pane-1 claude                      │
+│ 16:18:42 spawn  pane-2 /bin/zsh -l                 │
+└────────────────────────────────────────────────────┘
+┌─panes──┐ ┌─● pane-1 · claude · INSIDE — Ctrl+Esc to exit┐
+│ ● 1 cla│ │                                            │
+│ ○ 2 sh │ │   (live terminal — claude renders here)    │
+│ ◄      │ │                                            │
+└────────┘ └────────────────────────────────────────────┘
+```
+
+(The `panes` strip only appears in **focused** layout. A pane's border turns
+heavy/green while you're INSIDE it.)
+
+## Where things live
+
+- `maestro/app.py` — Textual app, key bindings, focus-toggle, spawn/dismiss/focus
+- `maestro/panes.py` — `Pane` model + `PaneManager` state machine (Textual-agnostic)
+- `maestro/layouts.py` — split / grid / focused renderers + the focus tiles strip
+- `maestro/terminal.py` — pyte-backed `Emulator`, `TerminalView`, query responder, key encoder
+- `maestro/agent.py` — PTY-backed subprocess wrapper (`ptyprocess`); raw bytes + resize
+- `maestro/events.py` — append-only JSONL event log (`.maestro/session.jsonl`)
+
+`.maestro/state.json` persists your layout + timeline-visibility choices across
+restarts. Agent sessions themselves are not resumed.
+
+## Tests
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## Next steps
+
+- Provider adapters beyond `claude` / `$SHELL` (`codex`, `gemini`, `gh copilot`)
+- Claude Code skill passthrough (toggle `~/.claude/skills` per pane)
+- Prompt library + per-agent system prompts
+- Inter-agent message bus for "review on modify" workflows
+- Terminal niceties: mouse reporting, bracketed paste, configurable INSIDE-exit key

maestro_tui-0.1.0/docs/ROADMAP.md

@@ -0,0 +1,85 @@
+# Maestro — Feature Roadmap
+
+Living list of shipped features and suggested next ones. Vision: **"PromptOps in a
+terminal, simpler"** — orchestrate multiple Claude Code sessions in parallel inside one
+TUI. (See `docs/superpowers/specs/` for per-feature design specs.)
+
+Last updated: 2026-05-27
+
+---
+
+## ✅ Shipped
+
+| Feature | How | Spec |
+| --- | --- | --- |
+| Multi-agent panes | split / grid / focused layouts, `Ctrl+L`; sticky completed | `2026-05-27-multi-agent-panes-design.md` |
+| Full ANSI terminal rendering | pyte emulator per pane; `claude`/`vim`/`htop` render | `2026-05-27-ansi-terminal-rendering-design.md` |
+| Focus-toggle interaction | `Enter` to interact, `Ctrl+Esc` to exit; click auto-enters | — |
+| Per-session status board | `▶` working / `⏳` waiting / `○` done / `✗` failed; `sessions` panel + header summary | — |
+| Skills launcher | `/` opens picker, injects `/name`; active-skill `⚡` badge | `2026-05-27-skill-passthrough-design.md` |
+| Broadcast input | `b` fans one prompt out to selected panes | `2026-05-27-broadcast-input-design.md` |
+| Quick agents | `a` launch/CRUD role templates (Reviewer, Tester, …); spawn + inject | `2026-05-27-quick-agents-design.md` |
+| Pane rename | `r` (blank resets to default) | — |
+| Quit | `q` (also `Ctrl+Q` where the terminal allows) | — |
+| Toggles | `Ctrl+B` sessions panel, `Ctrl+T` timeline | — |
+| Terminal-adaptive theme | defaults to `ansi-dark`; `Ctrl+P` to change; persists | — |
+| Clean-exit auto-dismiss | exit 0 auto-closes; failures stay sticky | — |
+
+---
+
+## 🌟 Suggested next — unique (lean into parallel orchestration)
+
+1. **Per-pane working directory / git worktree** ⭐ *top pick*
+   Spawn a pane in a different repo or a fresh `git worktree`, so N agents work N
+   branches without colliding. Makes parallel *coding* agents actually safe.
+
+2. **Desktop notification on waiting/exit**
+   Status detection already exists — fire an OS notification so you can background
+   maestro and get pulled back when a session needs you.
+
+3. **Inter-agent handoff**
+   Pipe one pane's output (or a selected block) into another's input: "coder finishes →
+   send summary to reviewer." PromptOps' "agents that hand off work" pillar.
+
+4. **Agent teams / squads**
+   One keypress spawns a *named group* of Quick Agents together (e.g. "Ship squad" =
+   Coder + Reviewer + Tester), optionally each in its own worktree. Builds on Quick
+   Agents (single) + per-pane worktree (#1). This is the "spawn a coordinated team"
+   idea — distinct from launching one Quick Agent.
+
+## 🔧 Suggested next — quality of life
+
+4. **Session save/restore** — relaunch and re-spawn the same panes (names, cwd, layout).
+   Quick-agent + pane names exist today but don't persist; this is the bigger version.
+5. **Scrollback / copy mode** — scroll a pane's history and copy text. pyte's
+   `HistoryScreen` already keeps it; just no viewer/selection yet.
+6. **Zoom a pane** — temporarily maximize the focused pane and back (tmux `prefix-z`),
+   independent of layout.
+7. **Reorder panes** — move a pane within the grid so related sessions sit together.
+8. **Transcript export** — dump a pane's scrollback to `.maestro/transcripts/pane-N.txt`.
+9. **Config file** (`~/.config/maestro/config.toml`) — default theme/layout, the
+   `WAITING_AFTER` threshold, custom agent types, keybindings.
+10. **Bell passthrough** — flash a pane's border when its program emits `\a`.
+
+## 🧩 Suggested next — bigger / ecosystem
+
+11. **Provider adapters** — `codex`, `gemini`, `gh copilot`, plus a custom "any command"
+    type. The `AGENT_TYPES` seam already exists in `maestro/panes.py`.
+12. **Prompt library** — saved, variable-fillable prompts injected into a pane
+    (`/prompt deploy-checklist`).
+
+---
+
+## Recommended order
+
+**Per-pane cwd/worktree (#1)** → **desktop notifications (#2)** → **session
+save/restore (#4)**. Highest value-to-effort first; per-pane worktree unlocks safe
+parallel coding, which is the core PromptOps use case.
+
+## Known limitations (accepted, by design)
+
+- Status detection is heuristic (output timing / Claude's output strings) — can't tell
+  "waiting for approval" from "waiting for your next message".
+- Keyboard-only inside panes — no mouse reporting, best-effort paste, no image protocols.
+- `Ctrl+Esc` exit needs a terminal that transmits it (kitty protocol / `modifyOtherKeys`).
+- Sessions/pane names are not persisted across restarts (until #5 lands).