Skip to main content

​
Frequently Asked Questions

Do my MCP tools, skills, and permissions work in Maestro? Yes. Maestro is a pass-through—it calls your provider (Claude Code, Codex, OpenCode) in batch mode rather than interactive mode. Whatever works when you run the provider directly will work in Maestro. Your MCP servers, custom skills, authentication, and tool permissions all carry over automatically. What’s the difference between running the provider directly vs. through Maestro? The only difference is execution mode. When you run Claude Code directly, it’s interactive—you send a message, watch it work, and respond in real-time. Maestro runs in batch mode: it sends a prompt, the provider processes it fully, and returns the response. This enables unattended automation via Auto Run and parallel agent management. Everything else—your tools, permissions, context—remains identical.

​
System Logs

Maestro maintains detailed system logs that help diagnose issues. Access them via:
  • Keyboard: Opt+Cmd+L (Mac) / Alt+Ctrl+L (Windows/Linux)
  • Quick Actions: Cmd+K / Ctrl+K → “View System Logs”
  • Menu: Click the hamburger menu (☰) in the Left Panel → “System Logs”
The System Log Viewer shows:
  • Timestamped log entries with severity levels (debug, info, warn, error, toast, autorun)
  • Filterable by log level via clickable level pills and searchable text (Cmd+F / Ctrl+F)
  • Real-time updates as new logs are generated
  • Detail view with full message content and source module
Log levels can be configured in Settings → General → System Log Level. Higher levels show fewer logs — Debug shows all logs, Error shows only errors.

​
Process Monitor

Monitor all running processes spawned by Maestro:
  • Keyboard: Opt+Cmd+P (Mac) / Alt+Ctrl+P (Windows/Linux)
  • Quick Actions: Cmd+K / Ctrl+K → “View System Processes”
  • Menu: Click the hamburger menu (☰) in the Left Panel → “Process Monitor”
The Process Monitor displays a hierarchical tree view:
  • Groups — Session groups containing their member sessions
  • Sessions — Each session shows its AI agent and terminal processes
  • Process details — PID, runtime, working directory, Claude session ID (for AI processes)
  • Group Chat processes — Moderator and participant processes for active group chats
  • Wizard processes — Active wizard conversations and playbook generation
Process types shown:
TypeDescription
AI AgentMain Claude Code (or other agent) process
TerminalShell process for the session
BatchAuto Run document processing agent
SynopsisContext compaction synopsis generation
ModeratorGroup chat moderator process
ParticipantGroup chat participant agent
WizardWizard conversation process
Wizard GenPlaybook document generation process
Features:
  • Click a process row to view detailed information (command, arguments, session ID)
  • Double-click or press Enter to navigate to the session/tab
  • K or Delete to kill a selected process
  • R to refresh the process list
  • Expand/collapse buttons in header to control tree visibility
This is useful when an agent becomes unresponsive or you need to diagnose process-related issues.

​
Agent Errors

When an AI agent encounters an error, Maestro displays a modal with clear recovery options. Common error types include:
Error TypeDescriptionRecovery Options
Authentication RequiredAPI key expired or invalidRe-authenticate, check API key settings
Context Limit ReachedConversation exceeded token limitStart new session, compact context
Rate Limit ExceededToo many API requestsWait and retry, reduce request frequency
Connection ErrorNetwork connectivity issueCheck internet, retry connection
Agent ErrorAgent process crashed unexpectedlyRestart agent, start new session
Permission DeniedFile or operation access deniedCheck permissions, run with appropriate access
Each error modal shows:
  • Error type and description
  • Agent and session context
  • Timestamp of when the error occurred
  • Collapsible JSON details for debugging
  • Recovery action buttons specific to the error type

​
Debug Package

If you encounter deep-seated issues that are difficult to diagnose, Maestro can generate a Debug Package — a compressed bundle of diagnostic information that you can safely share when reporting bugs. To create a Debug Package:
  1. Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open Quick Actions
  2. Search for “Create Debug Package”
  3. Choose a save location for the .zip file
  4. Attach the file to your GitHub issue

​
What’s Included

The debug package collects metadata and configuration — never your conversations or sensitive data: Always included:
FileContents
system-info.jsonOS, CPU, memory, Electron/Node versions, app uptime
settings.jsonApp preferences with sensitive values redacted
agents.jsonAgent configurations, availability, and capability flags
external-tools.jsonShell, git, GitHub CLI, and cloudflared availability
windows-diagnostics.jsonWindows-specific diagnostics (minimal on other platforms)
groups.jsonSession group configurations
processes.jsonActive process information
web-server.jsonWeb server and Cloudflare tunnel status
storage-info.jsonStorage paths and sizes
Optional (toggleable in UI):
FileContents
sessions.jsonSession metadata (names, states, tab counts — no conversations)
logs.jsonRecent system log entries
errors.jsonCurrent error states and recent error events
group-chats.jsonGroup chat metadata (participant lists, routing — no messages)
batch-state.jsonAuto Run state and document queue

​
Privacy Protections

The debug package is designed to be safe to share publicly:
  • API keys and tokens — Replaced with [REDACTED]
  • Passwords and secrets — Never included
  • Conversation content — Excluded entirely (no AI responses, no user messages)
  • File contents — Not included from your projects
  • Custom prompts — Not included (may contain sensitive context)
  • File paths — Sanitized to replace your username with ~
  • Environment variables — Only counts shown, not values (may contain secrets)
  • Custom agent arguments — Only [SET] or [NOT SET] shown, not actual values
Example path sanitization:
  • Before: /Users/johndoe/Projects/MyApp
  • After: ~/Projects/MyApp

​
WSL2 Issues (Windows)

If you’re running Maestro through WSL2, most issues stem from using Windows-mounted paths. See the WSL2 installation guide for the recommended setup.

​
Common WSL2 Problems

“EPERM: operation not permitted” on socket binding The Vite dev server or Electron cannot bind to ports when running from /mnt/... paths. Solution: Move your project to the native Linux filesystem: 
mv /mnt/c/projects/maestro ~/maestro
cd ~/maestro
npm install
npm run dev
“FATAL:sandbox_host_linux.cc” Electron crash The Electron sandbox cannot operate correctly on Windows-mounted filesystems. Solution: Run from the Linux filesystem (/home/...), not from /mnt/.... npm install timeouts or ENOTEMPTY errors Cross-filesystem operations between WSL and Windows are unreliable for npm’s file operations. Solution: Clone and install from the Linux filesystem: 
cd ~
git clone https://github.com/pedramamini/maestro.git
cd maestro
npm install
electron-rebuild failures The Windows temp directory may be inaccessible from WSL. Solution: Override the temp directory: 
TMPDIR=/tmp npm run rebuild
Git index corruption or lock file errors NTFS and Linux inode handling are incompatible, causing git metadata issues. Solution: If you see “missing index” or spurious .git/index.lock errors: 
rm -f .git/index.lock
git checkout -f
For new projects, always clone to the Linux filesystem from the start.

​
Getting Help