fix: argument denylist + Windows shell escaping #536

Original file line number	Diff line number	Diff line change
Expand Up		@@ -693,7 +693,7 @@ jobs:
		files: artifacts/release/*
		fail_on_unmatched_files: false
		draft: false
		prerelease: false
		prerelease: ${{ contains(github.ref_name, '-rc') \|\| contains(github.ref_name, '-RC') \|\| contains(github.ref_name, '-beta') \|\| contains(github.ref_name, '-alpha') }}
		generate_release_notes: true
		env:
		GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Expand Down

2 changes: 2 additions & 0 deletions .gitignore

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,6 +6,8 @@ Work\ Trees/
		community-data/
		.mcp.json
		specs/
		.maestro/
		maestro-cue.yaml

		# Tests
		coverage/
Expand Down

49 changes: 49 additions & 0 deletions ARCHITECTURE.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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)
Expand Down Expand Up		@@ -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.
Expand Down

35 changes: 35 additions & 0 deletions CLAUDE-IPC.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

Expand Down Expand Up		@@ -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,
		getActiveRuns: () => Promise,
		getActivityLog: (limit?) => Promise,

		// Engine controls
		enable: () => Promise,
		disable: () => Promise,

		// Run management
		stopRun: (runId) => Promise,
		stopAll: () => Promise,

		// Session config management
		refreshSession: (sessionId, projectRoot) => Promise,

		// YAML config file operations
		readYaml: (projectRoot) => Promise,
		writeYaml: (projectRoot, content) => Promise,
		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
Expand Down

13 changes: 11 additions & 2 deletions CLAUDE-PATTERNS.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.

4 changes: 2 additions & 2 deletions CLAUDE-WIZARD.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -38,7 +38,7 @@ src/renderer/components/Wizard/
		3. Conversation - AI asks clarifying questions, builds confidence score (0-100)
		4. Phase Review - View/edit generated Phase 1 document, choose to start tour

		When confidence reaches 80+ and agent signals "ready", user proceeds to Phase Review where Auto Run documents are generated and saved to `Auto Run Docs/Initiation/`. The `Initiation/` subfolder keeps wizard-generated documents separate from user-created playbooks.
		When confidence reaches 80+ and agent signals "ready", user proceeds to Phase Review where Auto Run documents are generated and saved to `.maestro/playbooks/initiation/`. The `initiation/` subfolder keeps wizard-generated documents separate from user-created playbooks.

		### Triggering the Wizard

Expand Down Expand Up		@@ -179,7 +179,7 @@ The Inline Wizard creates Auto Run Playbook documents from within an existing ag

		- Multiple wizards can run in different tabs simultaneously
		- Wizard state is per-tab (`AITab.wizardState`), not per-agent
		- Documents written to unique subfolder under Auto Run folder (e.g., `Auto Run Docs/Project-Name/`)
		- Documents written to unique subfolder under playbooks folder (e.g., `.maestro/playbooks/project-name/`)
		- On completion, tab renamed to "Project: {SubfolderName}"
		- Final AI message summarizes generated docs and next steps
		- Same `agentSessionId` preserved for context continuity
Expand Down

14 changes: 13 additions & 1 deletion CLAUDE.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down Expand Up		@@ -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)
Expand Down Expand Up		@@ -203,6 +209,12 @@ 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` \|
		\| Add terminal feature \| `src/renderer/components/XTerminal.tsx`, `src/renderer/components/TerminalView.tsx` \|
		\| Modify terminal tabs \| `src/renderer/utils/terminalTabHelpers.ts`, `src/renderer/stores/tabStore.ts` \|

		---

Expand Down

31 changes: 31 additions & 0 deletions docs/assets/theme-hint.js

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,31 @@
		/* global window, document, localStorage, URLSearchParams */
		/**
		* Theme Hint Script for Maestro Docs
		*
		* When the Maestro app opens a docs URL with a ?theme= query parameter,
		* this script sets the Mintlify theme to match.
		*
		* Supported values: ?theme=dark \| ?theme=light
		*
		* Mintlify stores the user's theme preference in localStorage under the
		* key "mintlify-color-scheme". Setting this key and dispatching a storage
		* event causes Mintlify to switch themes without a page reload.
		*/
		(function () {
		var params = new URLSearchParams(window.location.search);
		var theme = params.get('theme');

		if (theme === 'dark' \|\| theme === 'light') {
		// Mintlify reads this localStorage key for theme preference
		try {
		localStorage.setItem('mintlify-color-scheme', theme);
		} catch {
		// localStorage unavailable -- ignore
		}

		// Apply the class immediately to prevent flash of wrong theme
		document.documentElement.classList.remove('light', 'dark');
		document.documentElement.classList.add(theme);
		document.documentElement.style.colorScheme = theme;
		}
		})();

2 changes: 1 addition & 1 deletion docs/autorun-playbooks.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -42,7 +42,7 @@ Auto Run supports running multiple documents in sequence:
		2. Click + Add Docs to add more documents to the queue
		3. Drag to reorder documents as needed
		4. Configure options per document:
		- Reset on Completion - Creates a working copy in `Runs/` subfolder instead of modifying the original. The original document is never touched, and working copies (e.g., `TASK-1735192800000-loop-1.md`) serve as audit logs.
		- Reset on Completion - Creates a working copy in `runs/` subfolder instead of modifying the original. The original document is never touched, and working copies (e.g., `TASK-1735192800000-loop-1.md`) serve as audit logs.
		- Duplicate - Add the same document multiple times
		5. Enable Loop Mode to cycle back to the first document after completing the last
		6. Click Go to start running documents
Expand Down

96 changes: 96 additions & 0 deletions docs/deep-links.md

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -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.


		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.


		## Related

		- [Configuration](./configuration) -- OS notification settings
		- [General Usage](./general-usage) -- Core UI and workflow patterns
		- [MCP Server](./mcp-server) -- Connect AI applications to Maestro

17 changes: 13 additions & 4 deletions docs/docs.json

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,6 +9,7 @@
		"href": "https://runmaestro.ai"
		},
		"favicon": "/assets/icon.ico",
		"js": "/assets/theme-hint.js",
		"colors": {
		"primary": "#BD93F9",
		"light": "#F8F8F2",
Expand Down Expand Up		@@ -52,8 +53,6 @@
		"history",
		"context-management",
		"document-graph",
		"usage-dashboard",
		"symphony",
		"git-worktrees",
		"group-chat",
		"remote-control",
Expand All		@@ -74,15 +73,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"
		},
		{
Expand Down

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: argument denylist + Windows shell escaping #536

Are you sure you want to change the base?

Uh oh!

fix: argument denylist + Windows shell escaping #536

Filter by extension

Uh oh!

Diff view

Diff view

Uh oh!

There are no files selected for viewing

Uh oh!

Uh oh!