jlengrand/Maestro
1
0
Fork 0
mirror of https://github.com/jlengrand/Maestro.git synced 2026-03-10 08:31:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

split dev notes out of readme

Browse Source
This commit is contained in:
Pedram Amini
2025-11-25 14:35:46 -06:00
parent 842ca15a65
commit 3d770011ab
2 changed files with 298 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
CONTRIBUTING.md
View File

@@ -1,23 +1,189 @@
# Contributing to Maestro
Thank you for your interest in contributing to Maestro! This document provides guidelines and instructions for contributing.
Thank you for your interest in contributing to Maestro! This document provides guidelines, setup instructions, and architectural information for developers.
## Table of Contents
- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
- [Tech Stack](#tech-stack)
- [Development Scripts](#development-scripts)
- [Architecture](#architecture)
- [Code Style](#code-style)
- [Commit Messages](#commit-messages)
- [Pull Request Process](#pull-request-process)
- [Building for Release](#building-for-release)
- [GitHub Actions Workflow](#github-actions-workflow)
## Development Setup
1. Fork and clone the repository
2. Install dependencies: `npm install`
3. Start development server: `npm run dev`
### Prerequisites
- Node.js 20+
- npm or yarn
- Git
### Getting Started
```bash
# Fork and clone the repository
git clone <your-fork-url>
cd maestro
# Install dependencies
npm install
# Run in development mode with hot reload
npm run dev
```
## 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 Process)
- **Electron 28+** - Desktop application framework
- **TypeScript** - Type-safe JavaScript
- **node-pty** - Terminal emulation for shell sessions
- **Fastify** - High-performance web server for remote access
- **electron-store** - Persistent settings storage
### Frontend (Renderer Process)
- **React 18** - UI framework
- **TypeScript** - Type-safe JavaScript
- **Tailwind CSS** - Utility-first CSS framework
- **Vite** - Fast build tool and dev server
- **Lucide React** - Icon library
- **marked** - Markdown rendering
- **react-syntax-highlighter** - Code syntax highlighting
- **ansi-to-html** - Terminal ANSI escape code rendering
- **dompurify** - HTML sanitization for XSS prevention
- **emoji-mart** - Emoji picker component
## Development Scripts
```bash
# Start dev server with hot reload
npm run dev
# Build main process only (Electron backend)
npm run build:main
# Build renderer only (React frontend)
npm run build:renderer
# Full production build
npm run build
# Start built application
npm start
# Clean build artifacts and cache
npm run clean
```
## Architecture
### Process Management
Maestro uses a dual-process architecture where **each session runs two processes simultaneously**:
1. **AI Agent Process** - Runs Claude Code as a child process
2. **Terminal Process** - Runs a PTY shell session for command execution
This architecture enables seamless switching between AI and terminal modes without process restarts. All processes are managed through IPC (Inter-Process Communication) with secure context isolation.
### Security Model
Maestro implements strict security measures:
- **Context isolation enabled** - Renderer has no direct Node.js access
- **No node integration in renderer** - No `require()` in renderer process
- **Secure IPC via preload script** - Minimal API exposed via `contextBridge`
- **No shell injection** - Uses `execFile` instead of `exec`
- **Input sanitization** - All user inputs are validated
### Main Process (Backend)
Located in `src/main/`:
- `index.ts` - Application entry point, IPC handler registration, window management
- `process-manager.ts` - Core primitive for spawning and managing CLI processes
- `web-server.ts` - Fastify-based HTTP/WebSocket server for remote access
- `agent-detector.ts` - Auto-detects available AI tools via PATH
- `preload.ts` - Secure IPC bridge via contextBridge
### Renderer Process (Frontend)
Located in `src/renderer/`:
- `App.tsx` - Main UI coordinator
- `main.tsx` - Renderer entry point
- `components/` - React components (modals, panels, UI elements)
- `hooks/` - Custom React hooks for reusable state logic
- `services/` - Business logic services (clean wrappers around IPC calls)
- `constants/` - Application constants (themes, shortcuts, etc.)
## Code Style
- TypeScript for all new code
- Use ESLint and Prettier (configs coming soon)
- Follow existing code patterns
- Add JSDoc comments for public APIs
### TypeScript
- All code must be TypeScript with strict mode enabled
- Define interfaces for all data structures
- Export types via `preload.ts` for renderer types
### React Components
- Use functional components with hooks
- Keep components small and focused
- Use Tailwind CSS for styling
- Maintain keyboard accessibility
- Use inline styles for theme colors, Tailwind for layout
### Architecture Guidelines
**Main Process:**
- Keep IPC handlers simple and focused
- Use TypeScript interfaces for all data structures
- Handle errors gracefully
- No blocking operations
**Renderer Process:**
- Use React hooks
- Keep components small and focused
- Use Tailwind for styling
- Maintain keyboard accessibility
**Security:**
- Never expose Node.js APIs to renderer
- Use preload script for all IPC
- Sanitize all user inputs
- Use `execFile` instead of `exec`
## Commit Messages
Use conventional commits:
- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation changes
@@ -36,25 +202,54 @@ Example: `feat: add context usage visualization`
5. Submit PR with clear description
6. Wait for review
## Architecture Guidelines
## Building for Release
### Main Process (Backend)
- Keep IPC handlers simple and focused
- Use TypeScript interfaces for all data structures
- Handle errors gracefully
- No blocking operations
### 1. Prepare Icons
### Renderer Process (Frontend)
- Use React hooks
- Keep components small and focused
- Use Tailwind for styling
- Maintain keyboard accessibility
Place your application icons in the `build/` directory:
### Security
- Never expose Node.js APIs to renderer
- Use preload script for all IPC
- Sanitize all user inputs
- Use `execFile` instead of `exec`
- `icon.icns` - macOS (512x512 or 1024x1024)
- `icon.ico` - Windows (256x256)
- `icon.png` - Linux (512x512)
### 2. Update Version
Update version in `package.json`:
```json
{
"version": "0.1.0"
}
```
### 3. Build Distributables
```bash
# Build for all platforms
npm run package
# Platform-specific builds
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:**
```bash
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
## Testing

327
README.md
View File

@@ -2,7 +2,37 @@
> A unified, highly-responsive developer command center for managing your fleet of AI coding agents.
Maestro is a desktop application built with Electron that allows you to run and manage multiple AI coding instances instances in parallel with a Linear/Superhuman-level responsive interface. Currently supporting Claude Code with plans for additional agentic coding tools (Aider, OpenCode, etc.) may be added in the future based on user demand.
Maestro is a desktop application that allows you to run and manage multiple AI coding instances in parallel with a Linear/Superhuman-level responsive interface. Currently supporting Claude Code with plans for additional agentic coding tools (Aider, OpenCode, etc.) based on user demand.
## Installation
### Download
Download the latest release for your platform from the [Releases](https://github.com/pedramamini/maestro/releases) page:
- **macOS**: `.dmg` or `.zip`
- **Windows**: `.exe` installer
- **Linux**: `.AppImage`, `.deb`, or `.rpm`
### Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
- Git (optional, for git-aware features)
## Features
- 🚀 **Multi-Instance Management** - Run multiple Claude Code instances and Command Terminal sessions simultaneously
- 🔄 **Dual-Mode Input** - Switch between Command Terminal and AI Terminal seamlessly
- ⌨️ **Keyboard-First Navigation** - Full keyboard control with customizable shortcuts
- 🎨 **Beautiful Themes** - 12 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, and more
- 🔀 **Git Integration** - Automatic git status, diff tracking, and workspace detection
- 📁 **File Explorer** - Browse project files with syntax highlighting and markdown preview
- 📋 **Session Management** - Group, rename, and organize your sessions
- 📝 **Scratchpad** - Built-in markdown editor with live preview
- ⚡ **Slash Commands** - Extensible command system with autocomplete
- 🌐 **Remote Access** - Built-in web server with optional ngrok/Cloudflare tunneling
> **Note**: Maestro currently supports Claude Code only. Support for other agentic coding tools may be added in future releases based on community demand.
## UI Overview
@@ -12,266 +42,70 @@ Maestro features a three-panel layout:
- **Main Window** - Center workspace with two modes:
- **AI Terminal** - Interact with Claude Code AI assistant
- **Command Terminal** - Execute shell commands and scripts
- **File Preview** - View images and text documents wtih source highlighting and markdown rendering
- **File Preview** - View images and text documents with source highlighting and markdown rendering
- **Diff Preview** - View the current diff when working in Git repositories
- **Right Bar** - File explorer, command history, and scratchpad
### Session Status Indicators
Each session shows a color-coded status indicator:
- 🟢 **Green** - Ready and waiting
- 🟡 **Yellow** - Agent is thinking
- 🔴 **Red** - No connection with agent
- 🟠 **Pulsing Orange** - Attempting to establish connection
## Features
- 🚀 **Multi-Instance Management** - Run multiple Claude Code instances and Command Terminal sessions simultaneously
- 🎨 **Beautiful UI** - Obsidian-inspired themes with keyboard-first navigation
- 🔄 **Dual-Mode Input** - Switch between Command Terminal and AI Terminal seamlessly
- ⚡ **Slash Commands** - Extensible command system with autocomplete (`/clear` to clear output)
- 🌐 **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
> **Note**: Maestro currently supports Claude Code only. Support for other agentic coding tools may be added in future releases based on community demand.
## Quick Start
### Prerequisites
- Node.js 20+
- npm or yarn
- Git (optional, for git-aware features)
### Installation
```bash
# 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
```bash
# 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)
- ansi-to-html (ANSI escape code rendering)
- dompurify (HTML sanitization)
- emoji-mart (emoji picker)
### Development Scripts
```bash
# 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`:
```json
{
"version": "0.1.0"
}
```
### 3. Build Distributables
```bash
# 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:**
```bash
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 architecture where **each session runs two processes simultaneously**:
1. **AI Agent Process** - Runs Claude Code as a child process
2. **Terminal Process** - Runs a PTY shell session for command execution
This architecture enables seamless switching between AI and terminal modes without process restarts. 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` |
| Move Session to Group | `⌘⇧M` | `Ctrl+Shift+M` |
| Previous Agent | `⌘⇧{` | `Ctrl+Shift+{` |
| Next Agent | `⌘⇧}` | `Ctrl+Shift+}` |
| Switch AI/Command Terminal | `⌘J` | `Ctrl+J` |
| Show Shortcuts Help | `⌘/` | `Ctrl+/` |
| Open Settings | `⌘,` | `Ctrl+,` |
| Quick Actions | `Cmd+K` | `Ctrl+K` |
| Toggle Sidebar | `Cmd+B` | `Ctrl+B` |
| Toggle Right Panel | `Cmd+\` | `Ctrl+\` |
| New Agent | `Cmd+N` | `Ctrl+N` |
| Kill Agent | `Cmd+Shift+Backspace` | `Ctrl+Shift+Backspace` |
| Move Session to Group | `Cmd+Shift+M` | `Ctrl+Shift+M` |
| Previous Agent | `Cmd+Shift+{` | `Ctrl+Shift+{` |
| Next Agent | `Cmd+Shift+}` | `Ctrl+Shift+}` |
| Switch AI/Command Terminal | `Cmd+J` | `Ctrl+J` |
| Show Shortcuts Help | `Cmd+/` | `Ctrl+/` |
| Open Settings | `Cmd+,` | `Ctrl+,` |
| Cycle Focus Areas | `Tab` | `Tab` |
| Cycle Focus Backwards | `⇧Tab` | `Shift+Tab` |
| Cycle Focus Backwards | `Shift+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` |
| Go to Files Tab | `Cmd+Shift+F` | `Ctrl+Shift+F` |
| Go to History Tab | `Cmd+Shift+H` | `Ctrl+Shift+H` |
| Go to Scratchpad | `Cmd+Shift+S` | `Ctrl+Shift+S` |
| Toggle Markdown Raw/Preview | `Cmd+E` | `Ctrl+E` |
### Input & Output
| Action | Key |
|--------|-----|
| Send Message | `Enter` or `⌘Enter` (configurable in Settings) |
| Multiline Input | `⇧Enter` |
| Navigate Command History | `↑` while in input |
| Slash Commands | Type `/` to open autocomplete, `↑`/`↓` to navigate, `Tab`/`Enter` to select |
| Send Message | `Enter` or `Cmd+Enter` (configurable in Settings) |
| Multiline Input | `Shift+Enter` |
| Navigate Command History | `Up Arrow` while in input |
| Slash Commands | Type `/` to open autocomplete |
| 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 |
| Scroll Output | `Up/Down Arrow` while in output |
| Jump to Top/Bottom | `Cmd+Up/Down Arrow` while in output |
### Navigation & Search
| Action | Key |
|--------|-----|
| Navigate Sessions (Sidebar) | `↑` / `↓` while in sidebar |
| Navigate Sessions | `Up/Down Arrow` while in sidebar |
| Select Session | `Enter` while in sidebar |
| Open Session Filter | `/` while in sidebar |
| Navigate Files | `↑` / `↓` while in file tree |
| Navigate Files | `Up/Down Arrow` while in file tree |
| Open File Tree Filter | `/` while in file tree |
| Open File Preview | `Enter` on selected file |
| Close Preview/Filter/Modal | `Esc` |
@@ -280,39 +114,30 @@ This architecture enables seamless switching between AI and terminal modes witho
| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| Copy File Path | `⌘P` | `Ctrl+P` |
| Open Search in Preview | `/` | `/` |
| Scroll Preview | `↑` / `↓` | `↑` / `↓` |
| Close Preview | `Esc` | `Esc` |
| Copy File Path | `Cmd+P` | `Ctrl+P` |
| Open Search | `/` | `/` |
| Scroll | `Up/Down Arrow` | `Up/Down Arrow` |
| Close | `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*
*Most shortcuts are customizable in Settings > Shortcuts*
## Slash Commands
Maestro includes an extensible slash command system with autocomplete. Commands are executed in the input area and affect the current session.
### Available Commands
Maestro includes an extensible slash command system with autocomplete:
| Command | Description |
|---------|-------------|
| `/clear` | Clear the output history for the current mode (AI Terminal or Command Terminal) |
| `/clear` | Clear the output history for the current mode |
### Using Slash Commands
Type `/` in the input area to open the autocomplete menu, use arrow keys to navigate, and press `Tab` or `Enter` to select.
1. Type `/` in the input area to open the autocomplete menu
2. Use `↑`/`↓` arrow keys to navigate commands
3. Press `Tab` or `Enter` to select a command
4. Press `Esc` to dismiss the autocomplete menu
## Configuration
The slash command system is extensible - new commands can be added in `src/renderer/slashCommands.ts`.
Settings are stored in:
- **macOS**: `~/Library/Application Support/maestro/`
- **Windows**: `%APPDATA%/maestro/`
- **Linux**: `~/.config/maestro/`
## Remote Access
@@ -325,8 +150,14 @@ Maestro includes a built-in web server for remote access:
### Enabling Public Tunnels
1. Get an API token from [ngrok.com](https://ngrok.com) or Cloudflare
2. Open Settings → Network
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.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture details, and contribution guidelines.
## License
[MIT License](LICENSE)