Troubleshooting

Fresh

Diagnostic Tools

Tool	Shortcut	Purpose
System Log Viewer	Alt+Ctrl+L	Timestamped entries with severity levels
Process Monitor	Alt+Ctrl+P	Hierarchical tree of all spawned processes
Debug Package	Ctrl+K → "Create Debug Package"	Safe-to-share diagnostic ZIP

System Log Viewer

Severity levels: debug, info, warn, error, toast, autorun. Filterable by level, searchable by text. Configure log level in Settings → General.

Process Monitor

Shows hierarchical tree of all spawned processes:

• AI agents, terminals, batch jobs
• Synopsis generators, group chat moderators/participants
• Wizard processes

Actions: Click for details, double-click to navigate to session, K/Delete to kill a process, R to refresh.

Debug Package

Safe-to-share ZIP that includes:

• System info
• Settings (redacted)
• Agent configurations
• Process info

Never includes: Conversation content, file contents, or actual API key values.

Common Issues

SSH Issues

Error	Fix
Permission denied (publickey)	Add key to ~/.ssh/authorized_keys on remote
Host key verification failed	ssh-keyscan hostname >> ~/.ssh/known_hosts
Enter passphrase for key	Add to agent: ssh-add ~/.ssh/your_key

WSL2 Issues

WSL2 Path Warning

Always clone and run from the native Linux filesystem (/home/...), never from Windows-mounted paths (/mnt/c/...).

Symptoms of wrong path:

• Socket binding failures
• Electron sandbox crashes
• npm install failures
• Git corruption

Context Issues

Problem	Solution
Context filling too fast	Compact at 60-70% (don't wait for red warning)
Lost context after compact	Use session tabs to separate distinct topics
Need context in another provider	Use "Send to Agent" from tab menu
Context too large to transfer	Enable "Clean Context" option during merge

Auto Run Issues

Problem	Solution
Tasks not executing	Check that .md files have - [ ] format
Context bleeding between tasks	Each task should get a fresh session — verify session IDs in History
Auto Run on same repo conflicting	Use Git Worktrees for parallel Auto Run
Playbook not loading	Check file paths in playbook configuration

Agent Issues

Problem	Solution
Agent shows red (disconnected)	Verify provider is installed and authenticated
Pulsing orange (stuck connecting)	Check network, restart agent
Agent not responding	Process Monitor → find and kill stuck process
Wrong model being used	Check agent settings and provider configuration

Performance Issues

Problem	Solution
Maestro slow to start	Check for large session files in storage directory
High memory usage	Close unused tabs, reduce max output lines in Display settings
Disk space growing	Run maestro-cli clean playbooks, remove old worktrees

Getting Help

1. Check the System Log Viewer for errors
2. Create a Debug Package to share with support
3. File issues at GitHub Issues

See Also

• Settings — Configure log levels and display
• SSH Remote — Detailed SSH troubleshooting