---

The Problem

Your AI agents are scattered across terminals, computers, and cloud servers. They forget everything between sessions. They can't talk to each other. You're the bottleneck - copy-pasting context, relaying messages, and manually coordinating their work.

The Solution

AI Maestro is an AI Agent Orchestrator that gives your agents superpowers:

• Persistent memory that grows over time (Code Graph + CozoDB)
• Direct agent-to-agent communication (no more playing messenger)
• Run agents anywhere - laptop, remote servers, Docker containers
• One dashboard to orchestrate them all

Your agents become a coordinated team, not isolated tools.

One Dashboard, Unlimited Machines

Your Browser (localhost:23000)
  ├─ MacBook Pro (Manager)
  │   ├─ project-manager
  │   └─ code-reviewer
  │
  ├─ Mac Mini (Worker - Tailscale)
  │   ├─ ios-build-agent
  │   └─ backend-heavy-lifting
  │
  └─ AWS Server (Worker - Tailscale)
      ├─ docker-deployments
      └─ integration-tests

Benefits:

• ✅ Distribute workload across multiple machines
• ✅ Leverage machine-specific capabilities (Mac for iOS, Linux for Docker)
• ✅ Scale horizontally - add more machines as needed
• ✅ Work from anywhere (Tailscale VPN)
• ✅ One click to switch between any agent on any machine

---

✨ Features

🌐 Manager/Worker Architecture (New in v0.8.0!)

Distribute your AI agents across unlimited machines - all managed from one browser dashboard.

⚠️ macOS 15+ Users: If setting up distributed workers, you MUST run ./scripts/fix-pm2-daemon.sh first to fix Local Network Privacy blocking. See Known Issues for details.

• Smart Discovery Wizard: Just enter a URL, AI Maestro auto-discovers and tests the connection
• Real-time Health Monitoring: Green/red/yellow indicators show worker status at a glance
• Seamless Experience: Remote agents work exactly like local ones (transparent WebSocket proxying)
• Secure by Default: Tailscale VPN integration for encrypted remote access
• Zero Configuration: Works out-of-the-box with local network or Tailscale IPs

Example Setup:

• Laptop (8GB RAM): Lightweight tasks, project management
• Desktop (32GB RAM): Heavy builds, large codebase analysis
• Cloud Server: Docker builds, CI/CD, platform-specific testing

→ See Setup Tutorial | Use Cases | Concepts Guide

Universal Agent Support

Works with any terminal-based AI:

• Claude Code
• Aider
• Cursor
• GitHub Copilot CLI
• OpenAI Codex
• Your custom AI scripts

Smart Organization

• 3-level hierarchy: Use hyphens to create structure (e.g., project-category-agent)
• Dynamic color coding: Each top-level category gets its own color automatically
• Visual hierarchy: Expandable accordion with icons
• Auto-grouping: Agents with hyphens are automatically organized
• Instant search: Find any agent immediately (coming in v1.1)

Agent Management

• Create agents from the UI
• Rename with a click
• Delete when done
• Notes for each agent (auto-saved to localStorage)
• Auto-discovery: Detects all your tmux sessions automatically

Agent Communication System

• File-Based Messaging: Persistent, structured messages between agents
  • Priorities: urgent | high | normal | low
  • Types: request | response | notification | update
  • Rich context: Attach metadata, requirements, code snippets
  • Unread-only filtering: Agents see only new messages
  • Auto-mark-as-read: Messages marked read after retrieval
  • Inbox & Outbox: Full send/receive tracking per agent
• Instant tmux Notifications: Real-time alerts for urgent matters
  • Popup notifications (non-intrusive)
  • Terminal injections (visible in history)
  • Formatted output (for critical alerts)
• CLI Tools: Shell scripts for command-line messaging (📁 View Scripts)
  • send-aimaestro-message.sh - Send structured messages
  • forward-aimaestro-message.sh - Forward messages between agents
  • check-and-show-messages.sh - Display inbox
  • check-new-messages-arrived.sh - Quick unread count
  • send-tmux-message.sh - Instant notifications
  • 📖 Installation Guide
• Web UI: Rich inbox/compose interface in Messages tab
• See 📬 Communication Docs for 5-minute setup

Agent Intelligence System (New in v0.11!)

Your AI agents become smarter over time with persistent memory and deep code understanding.

• Code Graph Visualization: Interactive graph showing your codebase structure
  • Multi-language support: Ruby, TypeScript, Python, and more
  • Visualize classes, functions, components, and their relationships
  • Filter by type: Files, Functions, Components
  • See imports, calls, extends, includes, associations
  • Focus mode to explore specific code paths
  • Delta Indexing: Only re-indexes changed files (~100ms vs 1000ms+ full re-index)
• Agent Subconscious: Background memory maintenance
  • Automatic conversation indexing for semantic search
  • Message checking for inter-agent communication
  • Self-staggering scheduler (scales to 100+ agents without CPU spikes)
  • Activity-aware intervals (faster when active, slower when idle)
• Conversation Memory: Full conversation history with search
  • Browse every conversation your agents have had
  • See thinking messages and tool usage
  • Search across all conversations semantically
  • Track model usage and conversation statistics
• Auto-Generated Documentation: Living documentation from your codebase
  • Automatically extracts and indexes code documentation
  • Search through all documented functions and classes

See Agent Intelligence Guide for setup and configuration

Portable Agents (New in v0.15!)

Move your AI agents anywhere. Export, import, transfer, and clone agents across machines.

• Export to .zip Files: Package agents with full configuration
  • Agent metadata, settings, and customizations
  • Message history (inbox/outbox)
  • Git repository associations
  • One-click download from agent profile
• Import from Any Source: Bring agents into new AI Maestro instances
  • Drag-and-drop or file picker
  • Automatic conflict detection
  • Preview before importing
• Cross-Host Transfer: Move agents between machines
  • Transfer to any connected worker host
  • Full data migration (messages, settings, repos)
• Clone & Backup: Duplicate agents for experimentation
  • Create agent backups before major changes
  • Share agent configurations with teammates
  • Version your agent setups

See Multi-Computer Guide for detailed transfer workflows

Built for Speed

• WebSocket streaming for real-time terminal I/O
• No lag, no polling
• Keyboard shortcuts for power users
• Native macOS performance

Access from Anywhere

• Fully mobile-optimized interface for phones and tablets
• Touch-optimized controls with swipe gestures
• Secure remote access via Tailscale VPN
• Monitor agents while away from your desk
• See 📱 Mobile Access section below for setup and screenshots

---

🚀 Quick Start

Windows Users: See Windows Installation Guide for WSL2 setup (5-10 minutes)

Zero to Hero (Easiest - for new users)

macOS/Linux - One command installs everything:

curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh

With options:

# Install to custom directory
curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh -s -- -d ~/projects/ai-maestro

# Unattended install with auto-start
curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh -s -- --auto-start

# See all options
curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh -s -- --help

Windows - Install via WSL2:

# 1. Install WSL2 (PowerShell as Administrator)
wsl --install

# 2. Restart Windows, then in Ubuntu terminal:
curl -fsSL https://raw.githubusercontent.com/23blocks-OS/ai-maestro/main/scripts/remote-install.sh | sh

# 3. Access from Windows browser: http://localhost:23000

Full Windows guide: docs/WINDOWS-INSTALLATION.md

This installs:

• ✅ Homebrew (if needed)
• ✅ Node.js, Yarn, tmux (if needed)
• ✅ AI Maestro
• ✅ Agent messaging system (optional)
• ✅ All configuration

Time: 5-10 minutes (depending on what's already installed)

---

Manual Install (for developers)