RunMaestro · pedramamini · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,8 @@ Work\ Trees/
 community-data/
 .mcp.json
 specs/
+.maestro/
+maestro-cue.yaml
 
 # Tests
 coverage/

diff --git a/.prettierignore b/.prettierignore
@@ -4,3 +4,4 @@ node_modules/
 coverage/
 *.min.js
 .gitignore
+.prettierignore
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -18,6 +18,7 @@ Deep technical documentation for Maestro's architecture and design patterns. For
 - [Achievement System](#achievement-system)
 - [AI Tab System](#ai-tab-system)
 - [File Preview Tab System](#file-preview-tab-system)
+- [Terminal Tab System](#terminal-tab-system)
 - [Execution Queue](#execution-queue)
 - [Navigation History](#navigation-history)
 - [Group Chat System](#group-chat-system)
@@ -1116,6 +1117,54 @@ File tabs display a colored badge based on file extension. Colors are theme-awar
 
 ---
 
+## Terminal Tab System
+
+Persistent PTY-backed terminal tabs that integrate into the unified tab bar alongside AI and file tabs. Built on xterm.js for full terminal emulation with ANSI support.
+
+### Features
+
+- **Persistent PTY**: Each tab spawns a dedicated PTY via `process:spawnTerminalTab` IPC — the shell stays alive between tab switches
+- **xterm.js rendering**: Full terminal emulation via `XTerminal.tsx` (wraps `@xterm/xterm`); raw PTY data passes through unchanged
+- **Multi-tab**: Multiple independent shells per agent; tabs are closable and renameable
+- **State persistence**: `terminalTabs` array saved with the session; PTYs are re-spawned on restore
+- **Spawn failure UX**: `state === 'exited' && pid === 0` shows an error overlay with a Retry button
+- **Exit message**: PTY exit writes a yellow ANSI banner and new-terminal hint to the xterm buffer
+
+### Terminal Tab Interface
+
+```typescript
+interface TerminalTab {
+	id: string;            // Unique tab ID (UUID)
+	name: string;          // Display name (custom or auto "Terminal N")
+	shellType: string;     // Shell binary (e.g., "zsh", "bash")
+	cwd: string;           // Working directory
+	pid: number;           // PTY process ID (0 = not yet spawned)
+	state: 'idle' | 'running' | 'exited';
+	exitCode: number | null;
+	createdAt: number;
+}
+```
+
+### Session Fields
+
+```typescript
+// In Session interface
+terminalTabs: TerminalTab[];          // Array of terminal tabs
+activeTerminalTabId: string | null;   // Active terminal tab (null if not in terminal mode)
+```
+
+### Key Files
+
+| File                        | Purpose                                                              |
+| --------------------------- | -------------------------------------------------------------------- |
+| `XTerminal.tsx`             | xterm.js wrapper; handles PTY data I/O and terminal lifecycle        |
+| `TerminalView.tsx`          | Layout container; manages tab selection and spawn/exit state         |
+| `terminalTabHelpers.ts`     | CRUD helpers (`createTerminalTab`, `addTerminalTab`, `closeTerminalTab`, etc.) |
+| `tabStore.ts`               | Zustand selectors for terminal tab state                             |
+| `src/main/ipc/handlers/process.ts` | `process:spawnTerminalTab` IPC handler with SSH support       |
+
+---
+
 ## Execution Queue
 
 Sequential message processing system that prevents race conditions when multiple operations target the same agent.

diff --git a/CLAUDE-IPC.md b/CLAUDE-IPC.md
@@ -43,6 +43,7 @@ The `window.maestro` API exposes the following namespaces:
 - `history` - Per-agent execution history (see History API below)
 - `cli` - CLI activity detection for playbook runs
 - `tempfile` - Temporary file management for batch processing
+- `cue` - Maestro Cue event-driven automation (see Cue API below)
 
 ## Analytics & Visualization
 
@@ -74,6 +75,40 @@ window.maestro.history = {
 
 **AI Context Integration**: Use `getFilePath(sessionId)` to get the path to an agent's history file. This file can be passed directly to AI agents as context, giving them visibility into past completed tasks, decisions, and work patterns.
 
+## Cue API
+
+Maestro Cue event-driven automation engine. Gated behind the `maestroCue` Encore Feature flag.
+
+```typescript
+window.maestro.cue = {
+  // Query engine state
+  getStatus: () => Promise<CueSessionStatus[]>,
+  getActiveRuns: () => Promise<CueRunResult[]>,
+  getActivityLog: (limit?) => Promise<CueRunResult[]>,
+
+  // Engine controls
+  enable: () => Promise<void>,
+  disable: () => Promise<void>,
+
+  // Run management
+  stopRun: (runId) => Promise<boolean>,
+  stopAll: () => Promise<void>,
+
+  // Session config management
+  refreshSession: (sessionId, projectRoot) => Promise<void>,
+
+  // YAML config file operations
+  readYaml: (projectRoot) => Promise<string | null>,
+  writeYaml: (projectRoot, content) => Promise<void>,
+  validateYaml: (content) => Promise<{ valid: boolean; errors: string[] }>,
+
+  // Real-time updates
+  onActivityUpdate: (callback) => () => void,  // Returns unsubscribe function
+};
+```
+
+**Events:** `cue:activityUpdate` is pushed from main process on subscription triggers, run completions, config reloads, and config removals.
+
 ## Power Management
 
 - `power` - Sleep prevention: setEnabled, isEnabled, getStatus, addReason, removeReason

diff --git a/CLAUDE-PATTERNS.md b/CLAUDE-PATTERNS.md
@@ -348,16 +348,25 @@ When adding a new Encore Feature, gate **all** access points:
 6. **Hamburger menu** — Make the setter optional, conditionally render the menu item in `SessionList.tsx`
 7. **Command palette** — Pass `undefined` for the handler in `QuickActionsModal.tsx` (already conditionally renders based on handler existence)
 
-### Reference Implementation: Director's Notes
+### Reference Implementations
 
-Director's Notes is the first Encore Feature and serves as the canonical example:
+**Director's Notes** — First Encore Feature, canonical example:
 
 - **Flag:** `encoreFeatures.directorNotes` in `EncoreFeatureFlags`
 - **App.tsx gating:** Modal render wrapped in `{encoreFeatures.directorNotes && directorNotesOpen && (…)}`, callback passed as `encoreFeatures.directorNotes ? () => setDirectorNotesOpen(true) : undefined`
 - **Keyboard shortcut:** `ctx.encoreFeatures?.directorNotes` guard in `useMainKeyboardHandler.ts`
 - **Hamburger menu:** `setDirectorNotesOpen` made optional in `SessionList.tsx`, button conditionally rendered with `{setDirectorNotesOpen && (…)}`
 - **Command palette:** `onOpenDirectorNotes` already conditionally renders in `QuickActionsModal.tsx` — passing `undefined` from App.tsx is sufficient
 
+**Maestro Cue** — Event-driven automation, second Encore Feature:
+
+- **Flag:** `encoreFeatures.maestroCue` in `EncoreFeatureFlags`
+- **App.tsx gating:** Cue modal, hooks (`useCue`, `useCueAutoDiscovery`), and engine lifecycle gated on `encoreFeatures.maestroCue`
+- **Keyboard shortcut:** `ctx.encoreFeatures?.maestroCue` guard in `useMainKeyboardHandler.ts`
+- **Hamburger menu:** `setMaestroCueOpen` made optional in `SessionList.tsx`
+- **Command palette:** `onOpenMaestroCue` conditionally renders in `QuickActionsModal.tsx`
+- **Session list:** Cue status indicator (Zap icon) gated on `maestroCueEnabled`
+
 When adding a new Encore Feature, mirror this pattern across all access points.
 
 See [CONTRIBUTING.md → Encore Features](CONTRIBUTING.md#encore-features-feature-gating) for the full contributor guide.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -72,6 +72,11 @@ Use "agent" in user-facing language. Reserve "session" for provider-level conver
   - **Command Terminal** - Main window in terminal/shell mode
   - **System Log Viewer** - Special view for system logs (`LogViewer.tsx`)
 
+### Automation
+
+- **Cue** — Event-driven automation system (Maestro Cue), gated as an Encore Feature. Watches for file changes, time intervals, agent completions, GitHub PRs/issues, and pending markdown tasks to trigger automated prompts. Configured via `maestro-cue.yaml` per project.
+- **Cue Modal** — Dashboard for managing Cue subscriptions and viewing activity (`CueModal.tsx`)
+
 ### Agent States (color-coded)
 
 - **Green** - Ready/idle
@@ -131,9 +136,10 @@ src/
 │   ├── preload.ts          # Secure IPC bridge
 │   ├── process-manager.ts  # Process spawning (PTY + child_process)
 │   ├── agent-*.ts          # Agent detection, capabilities, session storage
+│   ├── cue/               # Maestro Cue event-driven automation engine
 │   ├── parsers/            # Per-agent output parsers + error patterns
 │   ├── storage/            # Per-agent session storage implementations
-│   ├── ipc/handlers/       # IPC handler modules (stats, git, playbooks, etc.)
+│   ├── ipc/handlers/       # IPC handler modules (stats, git, playbooks, cue, etc.)
 │   └── utils/              # Utilities (execFile, ssh-spawn-wrapper, etc.)
 │
 ├── renderer/               # React frontend (desktop)
@@ -202,6 +208,10 @@ src/
 | Add Director's Notes feature | `src/renderer/components/DirectorNotes/`, `src/main/ipc/handlers/director-notes.ts`                                                   |
 | Add Encore Feature           | `src/renderer/types/index.ts` (flag), `useSettings.ts` (state), `SettingsModal.tsx` (toggle UI), gate in `App.tsx` + keyboard handler |
 | Modify history components    | `src/renderer/components/History/`                                                                                                    |
+| Add Cue event type           | `src/main/cue/cue-types.ts`, `src/main/cue/cue-engine.ts`                                                                             |
+| Add Cue template variable    | `src/shared/templateVariables.ts`, `src/main/cue/cue-executor.ts`                                                                     |
+| Modify Cue modal             | `src/renderer/components/CueModal.tsx`                                                                                                |
+| Configure Cue engine         | `src/main/cue/cue-engine.ts`, `src/main/ipc/handlers/cue.ts`                                                                          |
 
 ---
 

diff --git a/docs/deep-links.md b/docs/deep-links.md
@@ -0,0 +1,96 @@
+---
+title: Deep Links
+description: Navigate to specific agents, tabs, and groups using maestro:// URLs from external apps, scripts, and OS notifications.
+icon: link
+---
+
+# Deep Links
+
+Maestro registers the `maestro://` URL protocol, enabling navigation to specific agents, tabs, and groups from external tools, scripts, shell commands, and OS notification clicks.
+
+## URL Format
+
+```
+maestro://[action]/[parameters]
+```
+
+### Available Actions
+
+| URL                                         | Action                                     |
+| ------------------------------------------- | ------------------------------------------ |
+| `maestro://focus`                           | Bring Maestro window to foreground         |
+| `maestro://session/{sessionId}`             | Navigate to an agent                       |
+| `maestro://session/{sessionId}/tab/{tabId}` | Navigate to a specific tab within an agent |
+| `maestro://group/{groupId}`                 | Expand a group and focus its first agent   |
+
+IDs containing special characters (`/`, `?`, `#`, `%`, etc.) are automatically URI-encoded and decoded.
+
+## Usage
+
+### From Terminal
+
+```bash
+# macOS
+open "maestro://session/abc123"
+open "maestro://session/abc123/tab/def456"
+open "maestro://group/my-group-id"
+open "maestro://focus"
+
+# Linux
+xdg-open "maestro://session/abc123"
+
+# Windows
+start maestro://session/abc123
+```
+
+### OS Notification Clicks
+
+When Maestro is running in the background and an agent completes a task, the OS notification is automatically linked to the originating agent and tab. Clicking the notification brings Maestro to the foreground and navigates directly to that agent's tab.
+
+This works out of the box — no configuration needed. Ensure **OS Notifications** are enabled in Settings.
+
+### Template Variables
+
+Deep link URLs are available as template variables in system prompts, custom AI commands, and Auto Run documents:
+
+| Variable              | Description                                    | Example Value                         |
+| --------------------- | ---------------------------------------------- | ------------------------------------- |
+| `{{AGENT_DEEP_LINK}}` | Link to the current agent                      | `maestro://session/abc123`            |
+| `{{TAB_DEEP_LINK}}`   | Link to the current agent + active tab         | `maestro://session/abc123/tab/def456` |
+| `{{GROUP_DEEP_LINK}}` | Link to the agent's group (empty if ungrouped) | `maestro://group/grp789`              |
+
+These variables can be used in:
+
+- **System prompts** — give AI agents awareness of their own deep link for cross-referencing
+- **Custom AI commands** — include deep links in generated output
+- **Auto Run documents** — reference agents in batch automation workflows
+- **Custom notification commands** — include deep links in TTS or logging scripts
+
+### From Scripts and External Tools
+
+Any application can launch Maestro deep links by opening the URL. This enables integrations like:
+
+- CI/CD pipelines that open a specific agent after deployment
+- Shell scripts that navigate to a group after batch operations
+- Alfred/Raycast workflows for quick agent access
+- Bookmarks for frequently-used agents
+
+## Platform Behavior
+
+| Platform          | Mechanism                                                                     |
+| ----------------- | ----------------------------------------------------------------------------- |
+| **macOS**         | `app.on('open-url')` delivers the URL to the running instance                 |
+| **Windows/Linux** | `app.on('second-instance')` delivers the URL via argv to the primary instance |
+| **Cold start**    | URL is buffered and processed after the window is ready                       |
+
+Maestro uses a single-instance lock — opening a deep link when Maestro is already running delivers the URL to the existing instance rather than launching a new one.
+
+<Note>
+In development mode, protocol registration is skipped by default to avoid overriding the production app's handler. Set `REGISTER_DEEP_LINKS_IN_DEV=1` to enable it during development.
+</Note>
+
+## Related
+
+- [Configuration](./configuration) — OS notification settings
+- [General Usage](./general-usage) — Core UI and workflow patterns
+- [MCP Server](./mcp-server) — Connect AI applications to Maestro
diff --git a/docs/docs.json b/docs/docs.json
@@ -52,11 +52,9 @@
 							"history",
 							"context-management",
 							"document-graph",
-							"usage-dashboard",
-							"symphony",
 							"git-worktrees",
 							"group-chat",
-							"remote-access",
+							"remote-control",
 							"ssh-remote-execution",
 							"configuration"
 						]
@@ -74,15 +72,25 @@
 					{
 						"group": "Encore Features",
 						"icon": "flask",
-						"pages": ["encore-features", "director-notes"]
+						"pages": [
+							"encore-features",
+							"director-notes",
+							"usage-dashboard",
+							"symphony",
+							"maestro-cue",
+							"maestro-cue-configuration",
+							"maestro-cue-events",
+							"maestro-cue-advanced",
+							"maestro-cue-examples"
+						]
 					},
 					{
 						"group": "Providers & CLI",
 						"pages": ["provider-notes", "multi-claude", "cli"]
 					},
 					{
 						"group": "Integrations",
-						"pages": ["mcp-server"],
+						"pages": ["mcp-server", "deep-links"],
 						"icon": "plug"
 					},
 					{

diff --git a/docs/encore-features.md b/docs/encore-features.md
@@ -16,11 +16,12 @@ Open **Settings** (`Cmd+,` / `Ctrl+,`) and navigate to the **Encore Features** t
 
 ## Available Features
 
-| Feature                              | Shortcut                       | Description                                                     |
-| ------------------------------------ | ------------------------------ | --------------------------------------------------------------- |
-| [Director's Notes](./director-notes) | `Cmd+Shift+O` / `Ctrl+Shift+O` | Unified timeline of all agent activity with AI-powered synopses |
-
-More features will be added here as they ship.
+| Feature                              | Shortcut                        | Description                                                                                      |
+| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [Director's Notes](./director-notes) | `Cmd+Shift+O` / `Ctrl+Shift+O` | Unified timeline of all agent activity with AI-powered synopses                                  |
+| [Usage Dashboard](./usage-dashboard) | `Opt+Cmd+U` / `Alt+Ctrl+U`     | Comprehensive analytics for tracking AI usage patterns                                           |
+| [Maestro Symphony](./symphony)       | `Cmd+Shift+Y` / `Ctrl+Shift+Y` | Contribute to open source by donating AI tokens                                                  |
+| [Maestro Cue](./maestro-cue)        | `Cmd+Shift+Q` / `Ctrl+Shift+Q` | Event-driven automation: file changes, timers, agent chaining, GitHub polling, and task tracking  |
 
 ## For Developers