mirror of
https://github.com/jlengrand/Maestro.git
synced 2026-03-10 08:31:19 +00:00
3d593719fb
This is a complete rewrite of SSH remote command execution that eliminates
all shell escaping issues by sending the entire script via stdin.
Previously, the SSH command was built as:
ssh host '/bin/bash -c '\''cd /path && VAR='\''value'\'' cmd arg'\'''
This required complex nested escaping that broke with:
- Heredocs (cat << 'EOF')
- Long prompts (command line length limits)
- Special characters in prompts
Now the SSH command is simply:
ssh host /bin/bash
And the entire script is piped via stdin:
export PATH="$HOME/.local/bin:..."
cd '/project/path'
export OPENCODE_CONFIG_CONTENT='{"permission":...}'
exec opencode run --format json 'prompt here'
Benefits:
- No shell escaping layers (stdin is binary-safe)
- No command line length limits
- Works with any remote shell (bash, zsh, fish)
- Handles any prompt content (quotes, newlines, $, etc.)
- Much simpler to debug and maintain
Changes:
- Add buildSshCommandWithStdin() in ssh-command-builder.ts
- Update process.ts to use stdin-based SSH for all agents
- Add sshStdinScript to ProcessConfig type
- Update ChildProcessSpawner to send stdin script
- Add comprehensive tests for new function
Maestro
Maestro hones fractured attention into focused intent.
Maestro is a cross-platform desktop app for orchestrating your fleet of AI agents and projects. It's a high-velocity solution for hackers who are juggling multiple projects in parallel. Designed for power users who live on the keyboard and rarely touch the mouse.
Collaborate with AI to create detailed specification documents, then let Auto Run execute them automatically, each task in a fresh session with clean context. Allowing for long-running unattended sessions, my current record is nearly 24 hours of continuous runtime.
Run multiple agents in parallel with a Linear/Superhuman-level responsive interface. Currently supporting Claude Code, OpenAI Codex, OpenCode, and Factory Droid with plans for additional agentic coding tools (Gemini CLI, Qwen3 Coder) based on user demand.
Features
Power Features
- 🌳 Git Worktrees - Run AI agents in parallel on isolated branches. Create worktree sub-agents from the git branch menu, each operating in their own directory. Work interactively in the main repo while sub-agents process tasks independently—then create PRs with one click. True parallel development without conflicts.
- 🤖 Auto Run & Playbooks - File-system-based task runner that batch-processes markdown checklists through AI agents. Create playbooks for repeatable workflows, run in loops, and track progress with full history. Each task gets its own AI session for clean conversation context.
- 💬 Group Chat - Coordinate multiple AI agents in a single conversation. A moderator AI orchestrates discussions, routing questions to the right agents and synthesizing their responses for cross-project questions and architecture discussions.
- 🌐 Mobile Remote Control - Built-in web server with QR code access. Monitor and control all your agents from your phone. Supports local network access and remote tunneling via Cloudflare for access from anywhere.
- 💻 Command Line Interface - Full CLI (
maestro-cli) for headless operation. List agents/groups, run playbooks from cron jobs or CI/CD pipelines, with human-readable or JSONL output for scripting. - 🚀 Multi-Agent Management - Run unlimited agents and terminal sessions in parallel. Each agent has its own workspace, conversation history, and isolated context.
- 📬 Message Queueing - Queue messages while AI is busy; they're sent automatically when the agent becomes ready. Never lose a thought.
Core Features
- 🔄 Dual-Mode Sessions - Each agent has both an AI Terminal and Command Terminal. Switch seamlessly between AI conversation and shell commands with
Cmd+J. - ⌨️ Keyboard-First Design - Full keyboard control with customizable shortcuts and mastery tracking that rewards you for leveling up.
Cmd+Kquick actions, rapid agent switching, and focus management designed for flow state. - 📋 Session Discovery - Automatically discovers and imports existing sessions from all supported providers, including conversations from before Maestro was installed. Browse, search, star, rename, and resume any session.
- 🔀 Git Integration - Automatic repo detection, branch display, diff viewer, commit logs, and git-aware file completion. Work with git without leaving the app.
- 📁 File Explorer - Browse project files with syntax highlighting, markdown preview, and image viewing. Reference files in prompts with
@mentions. - 🔍 Powerful Output Filtering - Search and filter AI output with include/exclude modes, regex support, and per-response local filters.
- ⚡ Slash Commands - Extensible command system with autocomplete. Create custom commands with template variables for your workflows.
- 💾 Draft Auto-Save - Never lose work. Drafts are automatically saved and restored per session.
- 🔊 Speakable Notifications - Audio alerts with text-to-speech announcements when agents complete tasks.
- 🎨 Beautiful Themes - 12 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, and more.
- 💰 Cost Tracking - Real-time token usage and cost tracking per session and globally.
- 🏆 Achievements - Level up from Apprentice to Titan of the Baton based on cumulative Auto Run time. 11 conductor-themed ranks to unlock.
Analytics & Visualization
- 📊 Usage Dashboard - Comprehensive analytics for tracking AI usage patterns across all sessions. View aggregated statistics with multiple time ranges (day, week, month, year, all time), compare agent performance, analyze user vs. Auto Run activity distribution, and explore activity heatmaps. Includes CSV export, real-time updates, and configurable colorblind-friendly palettes. Access via
Opt+Cmd+U(macOS) /Alt+Ctrl+U(Windows/Linux) or the Command K menu. - 🕸️ Document Graph - Visual knowledge graph of your markdown documentation. Automatically discovers internal
[[wiki-links]]and[markdown](links), visualizes document relationships with interactive nodes and edges. Toggle between force-directed and hierarchical layouts, search/filter documents, navigate via keyboard, and track external link references. Includes mini-map, legend, and pagination for large directories. Access from the File Explorer context menu or Command K menu.
Keyboard Shortcuts for Analytics Features
Usage Dashboard (Opt+Cmd+U / Alt+Ctrl+U):
| Action | Key |
|---|---|
| Navigate view tabs | Arrow Left/Right/Up/Down |
| Move between sections | Tab / Shift+Tab |
| Jump to first/last section | Home / End |
| Close dashboard | Escape |
Document Graph (Command K → "Document Graph"):
| Action | Key |
|---|---|
| Navigate to connected node | Arrow Up/Down/Left/Right |
| Cycle through connections | Tab |
| Open selected document/link | Enter |
| Close graph | Escape |
| Search documents | Focus search input, type query |
Additional interactions: Drag nodes to reposition, scroll to zoom, use mini-map for overview.
Note
: Maestro supports Claude Code, OpenAI Codex, OpenCode, and Factory Droid. Support for additional agents (Gemini CLI, Qwen3 Coder) may be added in future releases based on community demand.
Quick Start
Installation
Download the latest release for your platform from the Releases page.
Or build from source:
git clone https://github.com/pedramamini/Maestro.git
cd Maestro
npm install
npm run dev
Requirements
- At least one supported AI coding agent installed and authenticated:
- Claude Code - Anthropic's AI coding assistant
- OpenAI Codex - OpenAI's coding agent
- OpenCode - Open-source AI coding assistant
- Git (optional, for git-aware features)
Essential Keyboard Shortcuts
| Action | macOS | Windows/Linux |
|---|---|---|
| Quick Actions | Cmd+K |
Ctrl+K |
| New Agent | Cmd+N |
Ctrl+N |
| Switch AI/Terminal | Cmd+J |
Ctrl+J |
| Previous/Next Agent | Cmd+[ / Cmd+] |
Ctrl+[ / Ctrl+] |
| Toggle Sidebar | Cmd+B |
Ctrl+B |
| New Tab | Cmd+T |
Ctrl+T |
| Usage Dashboard | Opt+Cmd+U |
Alt+Ctrl+U |
| All Shortcuts | Cmd+/ |
Ctrl+/ |
Full keyboard shortcut reference
Screenshots
Main screen with multiple agents and conversation
Group Chat coordinates multiple AI agents in a single conversation
Quick Actions palette for rapid navigation (CTRL/CMD + K)
Git diff viewer with syntax highlighting
Documentation
Full documentation and usage guide available at docs.runmaestro.ai
- Installation
- Getting Started
- Features Overview
- Auto Run + Playbooks
- Git Worktrees
- Keyboard Shortcuts
- Context Management
- MCP Server - Connect AI apps to Maestro docs
- Troubleshooting
Community
- Discord: Join Us
- GitHub Issues: Report bugs & request features
Contributors
- @pedramamini - Creator and Benevolent Dictator
- @mattjay - Contributor and tester
- @chr1syy - Windows Contributor and tester
Contributing
See CONTRIBUTING.md for development setup, architecture details, and contribution guidelines.