Maestro

A unified, highly-responsive developer IDE for managing multiple AI coding assistants simultaneously.

Maestro is a desktop application built with Electron that allows you to run and manage multiple AI coding tools (Claude Code, Aider, OpenCode, etc.) in parallel with a Linear/Superhuman-level responsive interface.

Features

• 🚀 Multi-Instance Management - Run multiple AI assistants and terminal sessions simultaneously
• 🎨 Beautiful UI - Obsidian-inspired themes with keyboard-first navigation
• 🔄 Dual-Mode Input - Switch between terminal and AI interaction modes seamlessly
• 🌐 Remote Access - Built-in web server with optional ngrok/Cloudflare tunneling
• 🎯 Git Integration - Automatic git status, diff tracking, and workspace detection
• ⚡ Keyboard Shortcuts - Full keyboard control with customizable shortcuts
• 📝 Session Management - Group, rename, and organize your sessions
• 🎭 Multiple Themes - 8 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, Solarized, One Light, and Gruvbox
• 📄 File Explorer - Browse project files with syntax highlighting and markdown preview
• ✏️ Scratchpad - Built-in markdown editor with live preview

Quick Start

Prerequisites

• Node.js 20+
• npm or yarn
• Git (optional, for git-aware features)

Installation

# Clone the repository
git clone <repository-url>
cd maestro

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Package for distribution
npm run package

Platform-Specific Builds

# macOS only
npm run package:mac

# Windows only
npm run package:win

# Linux only
npm run package:linux

Development

Project Structure

maestro/
├── src/
│   ├── main/              # Electron main process (Node.js backend)
│   │   ├── utils/         # Shared utilities
│   │   └── ...            # Process management, IPC, web server
│   └── renderer/          # React frontend (UI)
│       ├── components/    # React components (UI elements, modals, panels)
│       ├── hooks/         # Custom React hooks (reusable state logic)
│       ├── services/      # Business logic services (git, process management)
│       ├── types/         # TypeScript definitions
│       ├── utils/         # Frontend utilities
│       └── constants/     # App constants (themes, shortcuts, emojis)
├── build/                 # Application icons
├── .github/workflows/     # CI/CD automation
└── dist/                  # Build output (generated)

Tech Stack

Backend (Electron Main)

• Electron 28+
• TypeScript
• node-pty (terminal emulation)
• Fastify (web server)
• electron-store (settings persistence)

Frontend (Renderer)

• React 18
• TypeScript
• Tailwind CSS
• Vite
• Lucide React (icons)
• marked (Markdown rendering)
• react-syntax-highlighter (code highlighting)
• emoji-mart (emoji picker)

Development Scripts

# Start dev server with hot reload
npm run dev

# Build main process only
npm run build:main

# Build renderer only
npm run build:renderer

# Full production build
npm run build

# Start built application
npm start

Building for Release

1. Prepare Icons

Place your application icons in the build/ directory:

• icon.icns - macOS (512x512 or 1024x1024)
• icon.ico - Windows (256x256)
• icon.png - Linux (512x512)

2. Update Version

Update version in package.json:

{
  "version": "0.1.0"
}

3. Build Distributables

# Build for all platforms
npm run package

# Platform-specific
npm run package:mac    # Creates .dmg and .zip
npm run package:win    # Creates .exe installer
npm run package:linux  # Creates .AppImage, .deb, .rpm

Output will be in the release/ directory.

GitHub Actions Workflow

The project includes automated builds via GitHub Actions:

1. Create a release tag:

   git tag v0.1.0
   git push origin v0.1.0
   

2. GitHub Actions will automatically:

   • Build for macOS, Windows, and Linux
   • Create release artifacts
   • Publish a GitHub Release with downloads

Configuration

Settings are stored in:

• macOS: ~/Library/Application Support/maestro/
• Windows: %APPDATA%/maestro/
• Linux: ~/.config/maestro/

Configuration Files

• maestro-settings.json - User preferences (theme, shortcuts, LLM settings, UI preferences)

Architecture

Process Management

Maestro uses a dual-process model:

1. PTY Processes - For terminal sessions (full shell emulation)
2. Child Processes - For AI tools (Claude Code, Aider, etc.)

All processes are managed through IPC (Inter-Process Communication) with secure context isolation.

Security

• ✅ Context isolation enabled
• ✅ No node integration in renderer
• ✅ Secure IPC via preload script
• ✅ No shell injection (uses execFile instead of exec)
• ✅ Input sanitization for all user inputs

Keyboard Shortcuts

Global Shortcuts

Action	macOS	Windows/Linux
Quick Actions	⌘K	Ctrl+K
Toggle Sidebar	⌘B	Ctrl+B
Toggle Right Panel	⌘\	Ctrl+\
New Agent	⌘N	Ctrl+N
Kill Agent	⌘⇧⌫	Ctrl+Shift+Backspace
Previous Agent	⌘⇧{	Ctrl+Shift+{
Next Agent	⌘⇧}	Ctrl+Shift+}
Switch AI/Shell Mode	⌘J	Ctrl+J
Show Shortcuts Help	⌘/	Ctrl+/
Open Settings	⌘,	Ctrl+,
Cycle Focus Areas	Tab	Tab
Cycle Focus Backwards	⇧Tab	Shift+Tab

Panel Shortcuts

Action	macOS	Windows/Linux
Go to Files Tab	⌘⇧F	Ctrl+Shift+F
Go to History Tab	⌘⇧H	Ctrl+Shift+H
Go to Scratchpad	⌘⇧S	Ctrl+Shift+S
Toggle Markdown Raw/Preview	⌘E	Ctrl+E

Input & Output

Action	Key
Send Message	Enter or ⌘Enter (configurable in Settings)
Multiline Input	⇧Enter
Navigate Command History	↑ while in input
Focus Output	Esc while in input
Focus Input	Esc while in output
Open Output Search	/ while in output
Scroll Output Up/Down	↑ / ↓ while in output
Jump to Top of Output	⌘↑ / Ctrl+↑ while in output
Jump to Bottom of Output	⌘↓ / Ctrl+↓ while in output

Navigation & Search

Action	Key
Navigate Sessions (Sidebar)	↑ / ↓ while in sidebar
Select Session	Enter while in sidebar
Open Session Filter	/ while in sidebar
Navigate Files	↑ / ↓ while in file tree
Open File Tree Filter	/ while in file tree
Open File Preview	Enter on selected file
Close Preview/Filter/Modal	Esc

File Preview

Action	macOS	Windows/Linux
Copy File Path	⌘P	Ctrl+P
Open Search in Preview	/	/
Scroll Preview	↑ / ↓	↑ / ↓
Close Preview	Esc	Esc

Quick Actions Modal

Action	macOS	Windows/Linux
Select Action 1-8	⌘1-8	Ctrl+1-8
Navigate Actions	↑ / ↓	↑ / ↓
Execute Action	Enter	Enter

Most shortcuts are customizable in Settings → Shortcuts

Remote Access

Maestro includes a built-in web server for remote access:

1. Local Access: http://localhost:8000
2. LAN Access: http://[your-ip]:8000
3. Public Access: Enable ngrok or Cloudflare tunnel in Settings

Enabling Public Tunnels

1. Get an API token from ngrok.com or Cloudflare
2. Open Settings → Network
3. Select your tunnel provider and enter your API key
4. Start the tunnel from the session interface

The web server provides REST API endpoints and WebSocket support for real-time session updates.