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. Claude said it was asking me a question, but no prompt appeared and the agent is stuck. Claude Code’s AskUserQuestion ask-back tool is only wired into Maestro when the tab is in Standard permission mode. In Standard mode, Maestro attaches a permission relay that renders the question as an in-app question picker (the same relay that surfaces tool approvals). In Full Access mode the relay is not attached (permission checks are bypassed with --dangerously-skip-permissions), so the question never reaches Maestro and the tool call waits forever, leaving the agent busy (yellow). To unstick it, stop the agent; a follow-up message only queues behind the stalled turn (which never completes), so it won’t dispatch and can’t recover the turn. If you want ask-back questions to work, switch the tab to Standard mode using the permission pill in the input toolbar. The same limitation applies in Read-Only mode. SSH remote agents can’t use Standard mode at all: a Standard-mode Claude Code spawn over SSH fails loudly instead of downgrading, so they always run in Full Access or Read-Only and never surface ask-backs.

​
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: 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: 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: Optional (toggleable in UI):

​
Privacy Protections

Support packages usually end up attached to a public GitHub issue, so the debug package is designed to be safe to share publicly - nothing in one identifies you or your work:
  • 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)
  • Your username and computer name - Replaced with [user] and [host] wherever they appear
  • File paths - Replaced with an opaque descriptor, so no folder, project, or repository names survive
  • Agent, session, and group names - Not included
  • SSH remote identities - Hosts and usernames replaced with [REDACTED]
  • URLs - Reduced to scheme and domain, so tunnel URLs cannot be reused
  • Environment variables - Only counts shown, not values (may contain secrets)
  • Custom agent arguments - Only [SET] or [NOT SET] shown, not actual values
Example path redaction:
  • Before: /Users/johndoe/Projects/MyApp/config.json
  • After: [path#3f9a1c04 root=home depth=3 ext=.json]
The descriptor keeps only what is useful for debugging: where the path starts (root), how deep it is (depth), the file extension, and flags for spaces or non-ASCII characters (a common cause of process spawn failures). The path# fingerprint is stable within a single package, so identical paths still line up, and it is salted per package so it cannot be reversed or matched against another package.

​
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:
“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:
electron-rebuild failures The Windows temp directory may be inaccessible from WSL. Solution: Override the temp directory:
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:
For new projects, always clone to the Linux filesystem from the start. Fonts not found The Interface Font picker in the Settings dialog asks Linux fontconfig what fonts exist in the WSL environment. It is not querying native Windows fonts directly; it’s using fc-list to resolve them, which by default only sees Linux-side fonts. To see Windows fonts, you need to teach fontconfig about /mnt/c/Windows/Fonts, then rebuild the font cache. Some fonts may also be stored in the user’s AppData\Local folder. To fix, update fontconfig’s configuration in WSL, replacing $USER accordingly:
Then rebuild the cache: fc-cache -f -v

​
Getting Help