claude-maestro 0.1.16

package/README.md

@@ -0,0 +1,130 @@
+# Maestro
+
+> ⚠️ **Disclaimer: this is a vibe-coded app.** Maestro was built almost entirely by Claude Code
+> (including by Maestro driving itself), with light human steering. Treat it as an experiment —
+> expect rough edges, review before relying on it, and use at your own risk.
+
+One window to run and **conduct** multiple Claude Code CLI sessions, each in its own repo, with a
+live file explorer per session and git-worktree parallel tasks. See [PLAN.md](./PLAN.md) and
+[SPECS.md](./SPECS.md).
+
+Each session embeds the **real, unmodified `claude` CLI** in a real pseudo-terminal (ConPTY on
+Windows, forkpty on macOS) — all CLI features (permission prompts, slash commands, `!` shell,
+paste, vim mode) work exactly as in a normal terminal. The app adds the frame: session registry,
+switching, status badges, file tree, viewer, parallel tasks, and restore-on-restart.
+
+Requires the `claude` CLI on PATH (`npm i -g @anthropic-ai/claude-code`).
+
+## Install
+
+**Windows** — grab either from the [latest release](https://github.com/pedroferreira1142/maestro/releases/latest):
+
+- `Maestro-<version>-portable.exe` — single file, run from anywhere, **no install, no admin rights**
+- `Maestro-Setup-<version>.exe` — per-user installer (Start menu + uninstaller, no admin rights)
+
+**macOS** — from the same release page:
+
+- `Maestro-<version>-arm64.dmg` (Apple Silicon) or `Maestro-<version>-x64.dmg` (Intel)
+- The app is unsigned: on first launch, right-click the app → **Open** (or
+  `xattr -d com.apple.quarantine /Applications/Maestro.app`).
+
+**npx / npm** (any OS with Node 20+; downloads Electron on first run):
+
+```bash
+npx claude-maestro
+# or install the command globally:
+npm i -g claude-maestro && claude-maestro
+```
+
+(Published to npm as [`claude-maestro`](https://www.npmjs.com/package/claude-maestro). You can also
+run the unpublished tip with `npx github:pedroferreira1142/maestro`.)
+
+## Develop
+
+```powershell
+npm install
+npm run dev        # development with HMR
+npm run build      # production bundles into out/
+npm run package    # build installers/portables into release/
+node bin/maestro.mjs   # run the built app
+```
+
+Cutting a release: see [RELEASING.md](RELEASING.md) for the SemVer policy and the
+`npm run release:patch|minor|major` scripts.
+
+## Use
+
+On macOS, `Cmd` works wherever `Ctrl` is listed (except `Ctrl+Tab`, which stays `Ctrl`).
+
+| Action | How |
+|---|---|
+| New session | `＋` in the sidebar, or `Ctrl+Shift+N` → pick a repo folder |
+| **New parallel task (worktree)** | `⑂` on a session, or `Ctrl+Shift+T` |
+| New terminal in session | `＋▾` in the tab strip, or `Ctrl+T` |
+| Switch session | Click in sidebar, `Ctrl+Tab` / `Ctrl+Shift+Tab`, or `Ctrl+1…9` |
+| Close session | ✕ on hover, or `Ctrl+Shift+W` |
+| Rename session | Double-click its name |
+| Toggle file explorer | `Ctrl+B` |
+| View a file | Single-click in the tree (read-only viewer tab) |
+| Open in editor | Double-click in the tree (default: VS Code) |
+| Context menu | Right-click a file/folder: open, reveal, copy path |
+| Terminal search | `Ctrl+F` in the terminal |
+| Copy / paste in terminal | `Ctrl+Shift+C` / `Ctrl+Shift+V`, right-click toggles copy/paste, `Ctrl+C` with selection copies |
+
+Sessions keep running in the background when not visible; scrollback is preserved. Status
+glyphs in the sidebar: `⟳` working · `●` needs your input · `○` idle · `✕` exited (with
+restart-resume buttons in the pane).
+
+On app restart, all sessions are restored and conversations resumed via `claude --continue`.
+
+## Parallel tasks (git worktrees)
+
+While Claude works on task A in a repo, spin off task B **on the same repo** without waiting:
+
+1. Click `⑂` on the session (or `Ctrl+Shift+T`). Name the task and pick its type — a branch
+   (`parallel/<slug>`, `feature/<slug>` or `bug/<slug>`) and a worktree folder
+   (`<repo>.worktrees/<slug>`, sibling of the repo) are created.
+2. A linked session appears indented under the parent, running its own `claude` in the
+   worktree — optionally pre-typed with your first prompt (you press Enter to send).
+3. When the task is done, click **Merge** on the task entry: the branch is merged
+   (`--no-ff`) into the base branch. Clean merge → offers to remove the worktree and
+   branch. Conflicts → you land in the terminal to resolve them like a normal merge.
+
+Any number of tasks can run side by side; each is isolated in its own working tree.
+
+### Reliable "needs input" detection
+
+Claude Code rings the terminal bell on prompts when configured to:
+
+```powershell
+claude config set --global preferredNotifChannel terminal_bell
+```
+
+With that set, background sessions flag themselves (badge + OS notification + taskbar flash)
+the moment Claude asks for permission or input. Without it, detection falls back to output
+heuristics.
+
+## State
+
+Session list, window bounds, and settings persist in `sessions.json` under the app's user-data
+dir (`%APPDATA%\maestro` on Windows, `~/Library/Application Support/maestro` on macOS). The tail
+of each terminal's output (~200 KB) is persisted under `scrollback/` in the same dir and replayed
+on restart above a dim `── restored from previous session ──` divider, while Claude's own
+`--continue` restores the conversation itself.
+
+## Architecture (short)
+
+- **Main process** (`src/main/`): `SessionManager` owns one `PtySession` (node-pty ConPTY
+  running `claude`) per session — PTYs live in main, so a renderer reload never kills sessions.
+  `StatusDetector` classifies the output stream; `FsService` does bounded chokidar watching
+  (root + expanded dirs, ignore-list at watcher level) and path-validated file reads.
+- **Preload** (`src/preload/`): typed `window.api` bridge, contextIsolation on.
+- **Renderer** (`src/renderer/`): React + zustand. One persistent xterm.js instance per
+  session (hidden, never unmounted ⇒ instant switching), lazy file tree with live updates and
+  changed-file flashes, CodeMirror 6 read-only viewer with auto language detection.
+
+## Acknowledgements
+
+This wouldn't have been possible without the help of
+[Tim Pieters](https://www.linkedin.com/in/tim-pieters/) and
+[Sven De Pickere](https://www.linkedin.com/in/svendepickere/).

package/bin/maestro.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * npx/CLI launcher for Maestro.
+ *
+ * Resolves the electron binary and boots the built app (out/ + package.json
+ * `main`). When the package was installed without electron (it's a devDep so
+ * electron-builder accepts it), falls back to running electron via npx, which
+ * downloads it into the npx cache on first use — no admin rights needed.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const appDir = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+if (!existsSync(join(appDir, 'out', 'main', 'index.js'))) {
+  console.error('Maestro: built app not found (out/main/index.js missing). Run "npm run build" first.')
+  process.exit(1)
+}
+
+const require = createRequire(import.meta.url)
+let electronPath = null
+try {
+  // In plain Node, require('electron') resolves to the binary's path.
+  const resolved = require('electron')
+  if (typeof resolved === 'string') electronPath = resolved
+} catch {
+  // electron not installed alongside the package — use the npx fallback below
+}
+
+// Windows needs shell:true to run npx.cmd; pass one pre-quoted string there
+// (args arrays + shell:true are deprecated, DEP0190).
+const child = electronPath
+  ? spawn(electronPath, [appDir], { stdio: 'inherit' })
+  : process.platform === 'win32'
+    ? spawn(`npx -y "electron@^33.3.0" "${appDir}"`, { stdio: 'inherit', shell: true })
+    : spawn('npx', ['-y', 'electron@^33.3.0', appDir], { stdio: 'inherit' })
+
+child.on('error', (err) => {
+  console.error('Maestro: failed to launch electron:', err.message)
+  process.exit(1)
+})
+child.on('close', (code) => process.exit(code ?? 0))