Skip to main content

​
Quick Diagnostics

Before diving into specific issues, use Maestro’s built-in diagnostic tools:
1

System Logs

Press Opt+Cmd+L (Mac) / Alt+Ctrl+L (Windows/Linux) to view system logs with:
  • Timestamped entries with severity levels
  • Filterable by log level (debug, info, warn, error)
  • Real-time updates as issues occur
  • Detail view with full message content
2

Process Monitor

Press Opt+Cmd+P (Mac) / Alt+Ctrl+P (Windows/Linux) to view:
  • All running agent processes
  • PIDs, runtimes, working directories
  • Group Chat moderator and participant processes
  • Process health and status
3

Debug Package

Press Cmd+K / Ctrl+K → “Create Debug Package” to generate:
  • System info (OS, CPU, memory, versions)
  • Settings (with sensitive data redacted)
  • Agent configurations and availability
  • Process information
  • Recent logs and errors

​
Common Issues

​
Agent Not Detected

Symptom: Provider doesn’t appear in agent creation dropdown. 
# Check if binary is in PATH
which claude      # Claude Code
which opencode    # OpenCode
which codex       # Codex
which droid       # Factory Droid

# If not found, install the provider
npm install -g @anthropic-ai/claude-code
  1. Open Settings → General (or Providers)
  2. Find the provider section
  3. Click Set Custom Path
  4. Browse to the binary location
  5. Click Save
  6. Restart Maestro
Settings → General → Check for Updates forces re-detection of all providers.

​
Authentication Errors

Symptom: Agent fails with “Authentication Required” or “Invalid API Key”. 
# Configure API key interactively
claude config

# Or set environment variable
export ANTHROPIC_API_KEY=sk-ant-...
API keys set via Maestro’s environment variables take precedence over system environment variables.

​
Context Limit Reached

Symptom: Agent responds with “Context window full” or “Max tokens reached”.
1

Use /compact (Claude Code)

Type /compact to compress conversation history.
2

Export and start fresh

  1. Right-click messages → Export Context
  2. Save important parts to a file
  3. Start a new tab for continued work
3

Adjust context warnings

Settings → Display → Context Window Warnings
  • Set warning threshold (e.g., 80%)
  • Get notified before hitting the limit

​
Agent Process Hangs

Symptom: Agent shows “busy” state indefinitely, no output.
  1. Press Opt+Cmd+P (Mac) / Alt+Ctrl+P (Windows/Linux)
  2. Select the hung process
  3. Press K or Delete to kill it
  4. Send a new message to restart the agent
  1. Press Opt+Cmd+L (Mac) / Alt+Ctrl+L (Windows/Linux)
  2. Filter by error level
  3. Look for stderr output or exit codes
  4. Address the root cause (missing dependency, permission issue, etc.)

​
Auto Run Not Starting

Symptom: Click “Run” but Auto Run doesn’t start.
  • Ensure documents exist in the Auto Run folder
  • Check that documents have unchecked checkboxes: - [ ]
  • Verify folder path is correct (not a symbolic link)
# Ensure Auto Run folder is writable
ls -la /path/to/autorun/folder

# Fix permissions if needed
chmod -R u+rw /path/to/autorun/folder
If loading a playbook:
  • Ensure all referenced documents exist
  • Check that document filenames match exactly (case-sensitive)
  • Verify loop settings (maxLoops should be null or positive integer)

​
Worktree Creation Fails

Symptom: Auto Run with worktree fails to create branch/directory. 
# Check if directory is a git repo
cd /path/to/project
git status

# Initialize if needed
git init
git commit --allow-empty -m "Initial commit"
  • Branch names cannot contain spaces
  • Avoid special characters except -, _, /
  • Ensure branch doesn’t already exist: git branch -a
# Ensure project directory is writable
ls -la /path/to/project

# Check existing worktrees
git worktree list

# Remove stale worktrees if needed
git worktree prune

​
SSH Remote Connection Fails

Symptom: Remote agent creation fails with “Connection refused” or timeout. 
# Test connection manually
ssh username@hostname -p 22

# If using SSH config
ssh config-host-name

# Test with verbose output
ssh -v username@hostname
If using SSH config import:
# Check ~/.ssh/config
cat ~/.ssh/config

# Ensure Host pattern matches
Host dev-server
    HostName 192.168.1.100
    User developer
    IdentityFile ~/.ssh/dev_key
    Port 2222
  • Ensure SSH port is open on remote host
  • Verify firewall rules allow incoming SSH
  • Test from another machine to isolate network issues

​
Image Attachments Not Working

Symptom: Image button is disabled or images don’t appear in agent output.
ProviderNew SessionResume Session
Claude Code✅✅
OpenCode✅✅
Codex✅❌
Codex doesn’t support images on resume—start a new tab for image input.
Supported formats: PNG, JPEG, GIF, WebPMaximum size: 5MB (provider-dependent)

​
Slash Commands Not Showing

Symptom: Typing / doesn’t show autocomplete menu.
Native slash commands are only available for Claude Code in batch mode.See Slash Commands for supported commands.
  1. Open Settings → AI Commands
  2. Ensure commands are saved
  3. Check trigger starts with /
  4. Verify no duplicate triggers

​
Platform-Specific Issues

​
Windows

Ensure provider binary is in Windows PATH:
  1. Search “Environment Variables” in Start menu
  2. Edit System PATH variable
  3. Add directory containing provider binary
  4. Restart Maestro
# Allow script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​
macOS

# Grant execute permission to binary
chmod +x /usr/local/bin/claude

# If installed via npm, may need to reinstall with proper permissions
sudo npm install -g @anthropic-ai/claude-code
For unsigned binaries:
  1. System Preferences → Security & Privacy
  2. Click “Allow” next to blocked app
  3. Or: xattr -d com.apple.quarantine /path/to/binary

​
Linux

Ensure D-Bus screen saver service is running:
# Check for running screensaver daemon
ps aux | grep screensaver

# Install xdg-screensaver if missing
sudo apt install xdg-utils

# Or for GNOME
sudo apt install gnome-screensaver
Minimal window managers (i3, dwm, sway) may not support sleep prevention.

​
WSL2 (Windows Subsystem for Linux)

EPERM: operation not permittedMove project to native Linux filesystem:
# Don't run from /mnt/c/...
mv /mnt/c/projects/maestro ~/maestro
cd ~/maestro
npm install
npm run dev
FATAL:sandbox_host_linux.ccRun from Linux filesystem (/home/...), not Windows-mounted paths (/mnt/...).
Override temp directory:
TMPDIR=/tmp npm install
See Troubleshooting for complete WSL2 guide.

​
Error Types & Recovery

Maestro categorizes agent errors for appropriate recovery:
Error TypeCauseRecovery
AuthenticationInvalid/expired API keyRe-authenticate, check credentials
Token ExhaustionContext window fullCompact, export, or start fresh
Rate LimitedToo many requestsWait and retry
Network ErrorConnection failedCheck internet, retry
Agent CrashedProcess exited unexpectedlyRestart agent, check logs
Permission DeniedFile/operation access blockedCheck permissions
Session Not FoundSession deleted or invalidStart new session
Each error modal provides context-specific recovery buttons.

​
Debug Mode

​
Enable Verbose Logging

1

Set log level

Settings → Display → System Log Level → Debug
2

View system logs

Press Opt+Cmd+L (Mac) / Alt+Ctrl+L (Windows/Linux)
3

Filter and search

  • Click log level pills to filter (debug, info, warn, error)
  • Use Cmd+F / Ctrl+F to search logs
  • Click entries for full detail view

​
Provider Debug Output

Enable debug output in provider-specific environment variables: 
# Claude Code debug output
CLAUDE_DEBUG=1

# Generic debug flag
DEBUG=*

# Maestro-specific debug
DEBUG=maestro:*
Set these in Settings → Providers → [Provider] → Environment Variables.

​
Reporting Issues

​
Creating a Debug Package

1

Generate package

  1. Press Cmd+K (Mac) / Ctrl+K (Windows/Linux)
  2. Search “Create Debug Package”
  3. Choose what to include:
    • System info (always included)
    • Session metadata (optional)
    • Logs (optional)
    • Errors (optional)
  4. Choose save location
2

Review contents

The debug package is sanitized for privacy:
  • API keys → [REDACTED]
  • Passwords → Never included
  • Conversation content → Excluded
  • File paths → Username replaced with ~
  • Environment variables → Only counts shown
3

Attach to issue

  1. Go to GitHub Issues
  2. Create new issue or comment on existing
  3. Attach the debug package .zip file
  4. Describe the problem and steps to reproduce

​
Privacy Protections

Debug packages are designed to be safe to share publicly:
Never included:
  • Conversation content
  • API keys or tokens
  • Passwords
  • File contents from your projects
  • Custom prompts (may contain context)
  • Environment variable values
Sanitized:
  • File paths (username → ~)
  • Custom arguments (shown as [SET] or [NOT SET])

​
What to Include in Reports

  1. Description: Clear explanation of the problem
  2. Steps to reproduce: Exact sequence to trigger the issue
  3. Expected behavior: What should happen
  4. Actual behavior: What actually happens
  5. Debug package: Attach the .zip file
  6. Screenshots: Visual aids for UI issues
  7. System info: OS, Maestro version, provider versions

​
Getting Help

GitHub Issues

Report bugs and request features

Discord Community

Get help from the community

Documentation

Browse complete docs

Contributing Guide

Development setup and processes

​
FAQ

Yes. Maestro calls your provider in batch mode rather than interactive mode. Whatever works when you run the provider directly will work in Maestro. MCP servers, custom skills, authentication, and tool permissions all carry over automatically.
The only difference is execution mode. Direct runs are interactive (you watch in real-time), while Maestro runs in batch mode (sends prompt, gets full response). This enables unattended automation and parallel agent management. Everything else—tools, permissions, context—remains identical.
These are interactive-only commands that require a TUI. For configuration, use the provider’s CLI directly: claude mcp or claude config.
See Multi-Claude for setting up multiple accounts with different API keys.

Build docs developers (and LLMs) love

Get started for freeTalk to us