Skip to main content

​
Download

Download the latest release for your platform from the Releases page:
  • macOS: .dmg or .zip (available for both Intel and Apple Silicon)
  • Windows: .exe installer or portable .exe (no installation required)
  • Linux: .AppImage, .deb, or .rpm (available for both x86_64 and arm64)
  • Upgrading: Simply replace the old binary with the new one. All your data (sessions, settings, playbooks, history) persists in your config directory.

​
Requirements

  • At least one supported AI coding agent installed and authenticated:
    • Claude Code — Anthropic’s AI coding assistant (fully integrated)
    • Codex — OpenAI’s coding agent (fully integrated)
    • OpenCode — Open-source AI coding assistant (fully integrated)
    • Factory Droid — Factory’s AI coding assistant (fully integrated)
    • Gemini CLI, Qwen3 Coder — Planned support
  • Git (optional, for git-aware features)
Maestro is a pass-through to your provider. Your MCP tools, custom skills, permissions, and authentication all work in Maestro exactly as they do when running the provider directly—Maestro just orchestrates the conversation flow in batch mode.

​
WSL2 Users (Windows Subsystem for Linux)

When developing or running Maestro with WSL2, always clone and run from the native Linux filesystem (e.g., /home/username/maestro), NOT from Windows-mounted paths (/mnt/c/..., /mnt/d/...).
Using Windows mounts causes several critical issues:
IssueSymptom
Socket binding failuresEPERM: operation not permitted when starting dev server
Electron sandbox crashesFATAL:sandbox_host_linux.cc errors
npm install failuresTimeouts, ENOTEMPTY rename errors
Git corruptionMissing index files, spurious lock files
# Clone to Linux filesystem (not /mnt/...)
cd ~
git clone https://github.com/pedramamini/maestro.git
cd maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

​
Accessing Files from Windows

You can browse your WSL2 files from Windows Explorer using: 
\\wsl$\Ubuntu\home\<username>\maestro

​
Troubleshooting WSL2

If you encounter electron-rebuild failures, try setting the temp directory: 
TMPDIR=/tmp npm run rebuild
For persistent issues, see Troubleshooting for additional WSL-specific guidance.

​
Building from Source

If you prefer to build Maestro from source: 
# Prerequisites: Node.js 22.0.0 or higher
node --version  # Verify version

# Clone the repository
git clone https://github.com/pedramamini/maestro.git
cd maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or build for production
npm run build
npm run package
Building from source requires native module compilation (node-pty, better-sqlite3). On Windows, you’ll need the Visual Studio Build Tools. On macOS, you’ll need Xcode Command Line Tools (xcode-select --install).