AI Maestro: Quick Start Guide

March 24, 2026 · View on GitHub

Get AI Maestro running in 5 minutes.

Prerequisites

  • macOS 12.0+ (Monterey or later) OR Windows 10+ (WSL2) OR Linux
  • Node.js 18.17+ or 20.x
  • tmux 3.0+
# macOS: Install dependencies (if not already installed)
brew install node tmux

# Linux/WSL: Install dependencies
sudo apt-get install -y nodejs npm tmux

Choose Your Installation Path

AI Maestro offers different installation options depending on your needs:

What You WantInstallation MethodTime
Full AI agent orchestration (dashboard, memory, messaging, all skills)Full Install5-10 min
Just the planning skill (no service needed)Plugin Only1 min
Try skills before committingPlugin Only, then Full Install1 min + 5 min

Full Installation

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

Unattended installation (for CI/CD, scripts, WSL):

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

This handles everything: prerequisites, installation, configuration. The -y flag skips all prompts.

What gets installed:

  • AI Maestro service (localhost:23000)
  • Web dashboard for managing agents
  • 32 CLI scripts in ~/.local/bin/
  • 5 Claude Code skills in ~/.claude/skills/
  • Prerequisites (Node.js, tmux, etc.) if needed

Option B: Manual Install

# Clone the repository
git clone https://github.com/23blocks-OS/ai-maestro.git
cd ai-maestro

# Install dependencies
yarn install
# or: npm install

# Build the application
yarn build
# or: npm run build

# Install CLI scripts and skills
./install-plugin.sh -y

Start AI Maestro

Development Mode:

yarn dev
# or: npm run dev

Production Mode (Recommended):

# Install pm2 globally
npm install -g pm2

# Start with pm2
pm2 start ecosystem.config.js

# Save pm2 process list
pm2 save

# Enable auto-start on boot
pm2 startup
# Follow the command it shows

Open in Browser

open http://localhost:23000

You're done! AI Maestro is now running with all features.

Plugin Only (Skills)

If you just want Claude Code skills without running the full AI Maestro service:

/plugin marketplace add 23blocks-OS/ai-maestro
/plugin install ai-maestro@ai-maestro-marketplace

IMPORTANT: Service Dependency

SkillWorks Without Service?
planningYES - Standalone
memory-searchNO - needs AI Maestro running
docs-searchNO - needs AI Maestro running
graph-queryNO - needs AI Maestro running
agent-messagingNO - needs AI Maestro running

Only the planning skill works standalone. For all other skills, install the full AI Maestro service.

The planning skill helps you stay focused on complex tasks by creating persistent markdown files:

  • task_plan.md - Your implementation plan
  • findings.md - Research and discoveries
  • progress.md - Step-by-step tracking

First Steps

Create Your First Agent

  1. Click the + button in the sidebar
  2. Enter an agent name (e.g., test-my-first-agent)
    • Use format: project-category-name for automatic grouping
    • Example: apps-website-frontend
  3. (Optional) Set working directory
  4. Click Create Agent

The agent will appear in the sidebar. Click it to open the terminal.

Test the Terminal

  1. Click on your newly created agent
  2. Type in the terminal: echo "Hello from AI Maestro"
  3. Try some commands: 
    pwd           # See current directory
ls            # List files
claude        # Start Claude Code (if installed)

Add Agent Notes

  1. Scroll down below the terminal
  2. Click Notes section (if collapsed)
  3. Type notes about what this agent is working on
  4. Notes auto-save to localStorage

Installation Comparison

FeatureFull InstallPlugin Only
Web dashboard✅❌
Agent management✅❌
Memory search skill✅❌ (needs service)
Docs search skill✅❌ (needs service)
Graph query skill✅❌ (needs service)
Agent messaging skill✅❌ (needs service)
Planning skill✅✅
CLI scripts in PATH✅❌
Hooks (session tracking)✅❌ (needs service)
Peer mesh network✅❌
Code graph visualization✅❌

Next Steps

Connect a Peer (Optional)

Want to manage agents across multiple machines? See Setup Tutorial.

Understand the Architecture

Read the Concepts Guide to learn about:

  • Localhost vs Remote Hosts
  • Peer mesh network
  • Security model

See Real-World Examples

Check out Use Cases for inspiration on how to leverage multiple machines.

Common Commands

# Start AI Maestro (development)
yarn dev

# Start AI Maestro (production with pm2)
pm2 start ai-maestro

# Stop AI Maestro
pm2 stop ai-maestro

# Restart AI Maestro
pm2 restart ai-maestro

# View logs
pm2 logs ai-maestro

# Check status
pm2 status

Keyboard Shortcuts

ShortcutAction
Shift + PageUpScroll up in terminal
Shift + PageDownScroll down in terminal
Cmd + CCopy selected text
Cmd + VPaste in terminal

Tips

  • Agent Naming: Use level1-level2-name format for automatic hierarchical organization

    • Example: clients-acme-frontend groups under "clients" → "acme"

  • Multiple Agents: Create as many as you need - they're organized automatically

  • Agent Notes: Document what each agent is working on

  • Settings: Click Settings (bottom of sidebar) to configure remote hosts

  • Immersive Mode: Click "Immersive Experience" for full-screen terminal view

Troubleshooting

AI Maestro won't start

# Check if port 23000 is in use
lsof -i :23000

# Kill process using port 23000
kill -9 <PID>

# Try different port
PORT=3000 yarn dev

Can't create agents

# Check if tmux is installed
tmux -V

# Test tmux manually
tmux new-session -s test
# Press Ctrl+B, then D to detach
tmux ls
# Should show: test: 1 windows

Skills not working (Plugin install)

If you installed via plugin marketplace and skills aren't working:

  1. Check if AI Maestro is running: curl http://localhost:23000/api/sessions
  2. If not running: Either start it (cd ~/ai-maestro && yarn dev) or use only the planning skill
  3. If not installed: Run the full installation

Terminal is blank

  1. Refresh the page (Cmd + R)
  2. Click refresh button in sidebar
  3. Check browser console for errors (F12)

Getting Help

Uninstall

# Stop AI Maestro
pm2 stop ai-maestro
pm2 delete ai-maestro
pm2 save

# Remove from auto-start
pm2 unstartup

# Delete repository
cd ..
rm -rf ai-maestro

# Remove pm2 (optional)
npm uninstall -g pm2

# Remove plugin (if installed via marketplace)
/plugin uninstall ai-maestro@ai-maestro-marketplace
/plugin marketplace remove ai-maestro-marketplace

Ready to scale? Check out the Setup Tutorial to connect peers and distribute your AI coding workforce across multiple machines!