Skip to content
/
Tier A A12 UI passthrough

Maestro (RunMaestro)

maestro-runmaestro · RunMaestro/Maestro · ★ 3.0k · last commit 2026-05-26

Primitive shape 1 total
Subagents 1
00

Summary

Maestro (RunMaestro) — Summary

Maestro is a cross-platform Electron desktop application and CLI for orchestrating multiple AI coding agent sessions (Claude Code, Codex, OpenCode, Factory Droid) in parallel, with git worktree isolation, a "Group Chat" multi-agent coordination feature, a file-based Auto Run/Playbooks system for batch task execution, mobile remote control, cost tracking, and an extensive keyboard-first interface.

Problem it solved: Developers juggling multiple parallel AI tasks face fragmented terminals, no unified session history, no automated playbook execution, and no way to coordinate multiple agents in a single conversation — Maestro provides one high-velocity desktop app that manages unlimited parallel agents, routes tasks to the right session, and can run unattended for up to 24 hours.

Distinctive traits: Three features set Maestro apart: (1) Group Chat — a moderator AI orchestrates multiple agent sessions in a single conversation, routing @mentions and synthesizing outputs; (2) Auto Run / Playbooks — a markdown-checklist-driven batch runner that processes tasks sequentially in fresh agent contexts; (3) maestro-cli — a full CLI binary for headless/cron operation.

Target audience: "Hackers juggling multiple projects in parallel" and power users who want a keyboard-first, highly customizable multi-agent environment with achievement gamification ("Apprentice to Titan of the Baton").

differs_from_seeds: Maestro is closest to superpowers in target tools (Claude Code, Codex) but inverts the model: instead of injecting skills into the agent, Maestro is an external orchestration shell that manages N agents simultaneously. The Group Chat feature introduces a novel moderator-agent pattern absent from all 11 seeds. Unlike claude-flow (MCP-anchored hive-mind), Maestro does not augment the agent's tool surface — it manages session dispatch and coordinates via a human-readable @mention protocol in a Group Chat window.

01

Overview

Maestro (RunMaestro) — Overview

Origin

Created by the RunMaestro team (runmaestro.ai). Licensed AGPL-3.0. Version 0.15.3. Actively maintained as of 2026-05-26.

Philosophy

"Maestro hones fractured attention into focused intent."

The README frames Maestro as a solution for "power users who live on the keyboard and rarely touch the mouse" who are "juggling multiple projects in parallel." The tool is explicitly designed for long-running unattended sessions — the README claims a personal record of "nearly 24 hours of continuous runtime."

Key belief: AI agents should be orchestrated like a team, not run serially. Each session gets clean context (fresh conversation per task), and the human's role is to define the playbook — not babysit individual tasks.

Manifesto-style quotes

"Maestro is a pass-through to your AI provider. Whatever MCP tools, skills, permissions, or authentication you have configured in Claude Code, Codex, or OpenCode works identically in Maestro. The only difference is we're not running interactively—each task gets a prompt and returns a response."

"My current record is nearly 24 hours of continuous runtime."

"Run multiple agents in parallel with a Linear/Superhuman-level responsive interface."

Gamification

Maestro includes an achievement system ("11 conductor-themed ranks") and "keyboard mastery tracking" that rewards users for learning shortcuts — a unique gamification layer among all frameworks in this corpus.

Target users

Solo developers managing multiple simultaneous projects, CI/CD power users who want to drive AI agents from cron jobs, teams wanting shared specification documents with AI execution.

02

Architecture

Maestro (RunMaestro) — Architecture

Distribution

  • Electron desktop app (macOS, Windows, Linux)
  • maestro-cli binary (shipped via bin.maestro-cli in package.json)
  • npm package: maestro v0.15.3

Install

# Desktop app: Download from GitHub Releases page
# From source:
git clone https://github.com/RunMaestro/Maestro
npm install
npm run dev

Directory structure

Maestro/
├── src/
│   ├── cli/             # maestro-cli CLI source
│   ├── main/            # Electron main process
│   ├── renderer/        # React renderer (frontend)
│   ├── prompts/         # Prompt template .md files
│   │   ├── maestro-system-prompt.md
│   │   ├── autorun-default.md
│   │   ├── autorun-synopsis.md
│   │   ├── group-chat-moderator-system.md
│   │   ├── group-chat-moderator-synthesis.md
│   │   ├── group-chat-participant.md
│   │   ├── group-chat-participant-request.md
│   │   ├── context-transfer.md
│   │   ├── context-summarize.md
│   │   ├── context-grooming.md
│   │   ├── commit-command.md
│   │   ├── director-notes.md
│   │   ├── tab-naming.md
│   │   ├── wizard-document-generation.md
│   │   └── wizard-inline-iterate*.md
│   ├── shared/          # Shared types
│   └── web/             # Web build (remote control)
├── e2e/                 # Playwright e2e tests
└── scripts/             # Build scripts

Required runtime

  • Node.js (Electron bundles runtime)
  • Git (for worktree features)
  • At least one of: Claude Code, Codex, OpenCode, Factory Droid (external, installed separately)

Target AI tools

  • Claude Code (primary)
  • OpenAI Codex
  • OpenCode
  • Factory Droid
  • (Gemini CLI planned)

Key technology

  • Electron + React (renderer)
  • TypeScript throughout
  • maestro-cli: dedicated Node CLI (./dist/cli/maestro-cli.js)
  • Slash commands system with autocomplete and template variables
  • Built-in web server for QR-code mobile access
  • Cloudflare tunnel integration for remote access
03

Components

Maestro (RunMaestro) — Components

CLI binary: maestro-cli

Subcommand Purpose
list agents List all configured agents/groups (human-readable or JSONL)
list groups List all Group Chat configurations
run playbook Execute a playbook from cron or CI/CD

Prompt templates (src/prompts/)

File Purpose
maestro-system-prompt.md Main system prompt injected for all Maestro-managed agents
autorun-default.md Prompt context for Auto Run task execution
autorun-synopsis.md Format for Auto Run task completion synopsis
group-chat-moderator-system.md System prompt for the Group Chat moderator AI
group-chat-moderator-synthesis.md Synthesis prompt after agents respond
group-chat-participant.md Prompt for participant agents in Group Chat
group-chat-participant-request.md Request format for @mentioning agents
context-transfer.md Context handoff between sessions
context-summarize.md Session summary generation
context-grooming.md Context window grooming instructions
commit-command.md Structured commit message prompt
director-notes.md Director notes format for agents
tab-naming.md Auto-name generation for session tabs
wizard-document-generation.md Spec document generation via wizard
wizard-inline-iterate.md Inline iteration during wizard
wizard-inline-iterate-generation.md Generation during inline iteration

UI features

Feature Purpose
Agent sessions pane Unlimited parallel agent sessions with per-session chat
Group Chat Moderator AI orchestrates multiple agents via @mentions
Git Worktrees Create/manage worktrees per agent session
Auto Run / Playbooks Batch markdown checklist execution in fresh contexts
Mobile Remote Control Built-in web server + QR code + Cloudflare tunnel
Usage Dashboard Analytics: tokens, costs, heatmaps, per-agent stats
Document Graph Visual wiki-link graph of markdown docs
File Explorer Browse project files, preview, image view
Output Filtering Regex-based filter/exclude on agent output
Slash Commands Extensible /command system with template vars
Draft Auto-Save Per-session draft persistence
Speakable Notifications TTS alerts when agents complete
Themes 12 themes (Dracula, Nord, Tokyo Night, etc.)
Cost Tracking Real-time token + dollar tracking per session
Achievements 11 gamification ranks (Apprentice → Titan)
05

Prompts

Maestro (RunMaestro) — Prompts

Verbatim excerpt 1: maestro-system-prompt.md

# Maestro System Context

You are **{{AGENT_NAME}}**, powered by **{{TOOL_TYPE}}**, operating as a Maestro-managed AI coding agent.

## About Maestro

Maestro is an Electron desktop application for managing multiple AI coding assistants simultaneously with a keyboard-first interface.

## Session Information

- **Agent Name:** {{AGENT_NAME}}
- **Agent Type:** {{TOOL_TYPE}}
- **Working Directory:** {{AGENT_PATH}}
- **Current Directory:** {{CWD}}
- **Git Branch:** {{GIT_BRANCH}}
- **Session ID:** {{AGENT_SESSION_ID}}

## Task Recall

Your session history is stored at `{{AGENT_HISTORY_PATH}}`. When you need context about previously completed tasks, read this JSON file and parse the `entries` array. Each entry contains:
- `summary`: Brief description of the task
- `timestamp`: When the task was completed (Unix ms)
- `type`: `AUTO` (automated) or `USER` (interactive)
- `success`: Whether the task succeeded
- `fullResponse`: Complete AI response text

## Critical Directive: Directory Restrictions

**You MUST only write files within your assigned working directory.**

Prompting technique: Identity injection + session context hydration + explicit directory constraint. Uses {{TEMPLATE_VARS}} substitution. The session history path enables cross-session recall without any shared memory system — agents read their own JSON log file.

Verbatim excerpt 2: group-chat-moderator-system.md

You are a Group Chat Moderator in Maestro, a multi-agent orchestration tool.

Your role is to:
1. **Assist the user directly** - You are a capable AI assistant. For simple questions or tasks, respond directly without delegating to other agents.
2. **Coordinate multiple AI agents** - When the user's request requires specialized help or parallel work, delegate to the available Maestro agents (sessions) listed below.
3. **Route messages via @mentions** - Use @AgentName format to address specific agents.
4. **Aggregate and summarize** - When multiple agents respond, synthesize their work into a coherent response for the user.

## Conversation Control:
- **You control the flow** - After agents respond, YOU decide what happens next
- If an agent's response is incomplete or unclear, @mention them again for clarification
- Only return to the user when you have a complete, actionable answer

## Auto Run Execution:
- Use `!autorun @AgentName:filename.md` to trigger execution of a specific Auto Run document
- Use `!autorun @AgentName` (without filename) only when you want to run ALL documents in the agent's Auto Run folder
- **Never ask an agent to execute/run/process an Auto Run document via a regular `@Agent` message.** Auto Run document execution must go through `!autorun`, not a normal participant prompt

Prompting technique: Role-based moderator with explicit authority model + protocol specification (!autorun vs @mention). This is a hierarchical multi-agent coordination protocol implemented entirely in the system prompt.

Verbatim excerpt 3: autorun-default.md (key design rules)

## CRITICAL: Response Format Requirement
**Your response MUST begin with a specific, actionable synopsis of what you accomplished.**
- GOOD: "Added pagination to the user list component"
- BAD: "The task is complete", "Done", "Finished the task"

## Structured Output Artifacts
When creating documentation, research notes, reports, use YAML Front Matter:
---
type: research | note | report | analysis | reference
title: Descriptive Title
tags: [...]
related: ['[[Other-Document]]']
---

Prompting technique: Output format enforcement + structured artifact schema. Maestro's Auto Run depends on parseable synopses for its history panel — the prompt enforces this.

09

Uniqueness

Maestro (RunMaestro) — Uniqueness & Positioning

differs_from_seeds

Maestro is the most feature-rich multi-session desktop manager in this batch, combining elements from multiple seed archetypes without fitting any cleanly. Unlike superpowers (14 skills injected via SessionStart hook), Maestro injects behavioral instructions via its own system prompt templates — but these are session management instructions, not methodology enforcement. Unlike claude-flow (hive-mind via 305 MCP tools), Maestro's Group Chat coordination is implemented in a moderator AI's system prompt, not in protocol-level tooling. The closest seed analog is taskmaster-ai in the sense that both support batch task processing, but taskmaster-ai uses MCP + JSON task lists while Maestro uses file-based markdown checklists. Maestro introduces an architectural novelty absent from all seeds: the Group Chat moderator pattern, where a dedicated AI instance manages agent routing and synthesis via @mention protocol — closest to a hierarchical orchestrator but implemented entirely via prompt engineering rather than code.

Positioning

  • "The Bloomberg Terminal for AI coding agents" (borrowing from its-maestro-baby's framing for the cluster)
  • Explicitly targets power users who want maximum velocity across many parallel projects
  • "Pass-through" philosophy: adds session management without modifying the underlying agent behavior
  • AGPL-3.0 license (most restrictive in this batch — commercial use requires source disclosure)

Observable failure modes

  • No automated merge or conflict resolution: human must review all session outputs
  • Group Chat coordination relies entirely on the moderator AI following the @mention protocol — hallucinations or protocol deviations are possible
  • Auto Run tasks run sequentially in fresh contexts: no state sharing between consecutive tasks (by design, but limiting)
  • AGPL license may deter commercial adoption

Inspired by

  • Linear and Superhuman (keyboard-first UI design philosophy)
  • Anthropic Claude Code SDK (pass-through architecture)

Competitors named in README

None explicitly.

Cross-references in this batch

  • its-maestro-baby/maestro is a separate, independent project with the same name but different architecture (Tauri/Rust vs Electron)
  • Parallel Code, 1Code, Crystal, Dorothy, agor all share the "parallel worktree manager" pattern at varying levels of sophistication
04

Workflow

Maestro (RunMaestro) — Workflow

Workflow modes

Mode 1: Interactive parallel sessions

Phase Action Artifact
Session creation Open Maestro, create N agent sessions N terminal sessions (optionally in git worktrees)
Parallel work Send prompts to each session; they run independently Per-session output
Monitoring Status indicators per session; message queueing Live output, queued messages
Integration Create PRs with one click from git branch menu GitHub PR

Mode 2: Auto Run / Playbooks (batch)

Phase Action Artifact
Playbook creation AI creates markdown checklist in AUTORUN_FOLDER .md files with - [ ] task checkboxes
Execution Maestro processes each checkbox in a fresh agent context Checked-off tasks with completion comments
Completion Synopsis reported back; loop continues Session history entry

Mode 3: Group Chat (multi-agent coordination)

Phase Action Artifact
Session assembly Open Group Chat with N participating agents Group Chat window
Moderator dispatch Moderator AI routes questions via @AgentName @mention messages to participants
Parallel work Each mentioned agent works in its own project context Per-agent responses
Synthesis Moderator synthesizes all responses for user Unified Group Chat response
Auto Run trigger !autorun @Agent:playbook.md to execute Playbook execution per agent
Commit !commit command → all agents commit on their branches Per-agent commits

Approval gates

  • No hard automated gates
  • User explicitly approves PR creation (one click)
  • !autorun must be explicitly issued by the user or moderator AI

Worktree dispatch

  • Git worktree sub-agents are created from the git branch menu per session
  • Each worktree agent operates independently; PRs are created manually via the UI
06

Memory Context

Maestro (RunMaestro) — Memory & Context

Session history (JSON file per agent)

Each agent has a history file at {{AGENT_HISTORY_PATH}} (a JSON file managed by Maestro). Entries contain:

  • summary: completion synopsis
  • timestamp: Unix milliseconds
  • type: AUTO | USER
  • success: boolean
  • fullResponse: full AI response text
  • elapsedTimeMs: task duration
  • contextUsage: context window usage % at completion

Agents are explicitly instructed in the system prompt to read this file to recall prior work. This is Maestro's primary cross-session memory mechanism — file-based JSON history, not a database or vector store.

Context grooming

Maestro includes context-summarize.md and context-grooming.md prompt templates that agents use to proactively summarize and compress context. Context transfer is also handled via context-transfer.md for handoffs between sessions.

Auto Run task tracking

Playbook .md files use - [ ] / - [x] checkbox syntax. Completed tasks are checked off with completion comments directly in the markdown file. This serves as a lightweight audit log.

Persistence

  • Session history JSON files: per-agent, file-system-based, persistent across app restarts
  • Playbook markdown files: checked off as tasks complete
  • Draft messages: auto-saved per session in Maestro's own store

Context compaction

Maestro provides context-grooming.md (proactive compression) and context-transfer.md (handoff). The agent is responsible for executing these; Maestro does not do automated compaction at the platform level.

State files

  • {{AGENT_HISTORY_PATH}}: per-agent JSON history file
  • Playbook .md files: in {{AUTORUN_FOLDER}}
  • Maestro's internal Electron data store (sessions, settings — not documented publicly)
07

Orchestration

Maestro (RunMaestro) — Orchestration

Multi-agent support

Yes — Maestro's core value is running unlimited parallel agent sessions.

Orchestration patterns

Maestro supports multiple patterns simultaneously:

  1. Parallel fan-out: Run N independent sessions with no coordination (default mode)
  2. Hierarchical (moderator + workers): Group Chat uses a moderator AI that routes work to participant agents via @mentions and synthesizes their outputs
  3. Sequential (Auto Run): Each checklist task runs in a fresh agent context sequentially; can be triggered in parallel across multiple agents via !autorun @Agent1:file.md + !autorun @Agent2:file.md in one message

Group Chat protocol

  • Moderator AI: receives user messages, decides whether to answer directly or delegate
  • Participant agents: receive @mention messages and work in their project contexts
  • @mention syntax: @AgentName your task here
  • Auto Run trigger: !autorun @AgentName:playbook.md
  • Commit trigger: !commit → all agents commit their branches
  • Coordination is implemented entirely via the moderator's system prompt — no protocol-level coordination

Isolation mechanism

Git worktree (optional): Agents can operate in git worktrees created from the branch menu. Not mandatory for all sessions.

Multi-model support

Yes — different sessions can use different underlying tools (Claude Code = Claude models, Codex = OpenAI models). Within a single tool, model selection is whatever the user has configured in that tool's own settings.

Execution mode

  • Interactive loop: Default session mode
  • Continuous / Auto Run: Playbooks can loop and run unattended for hours

Crash recovery

Sessions persist; Maestro can rediscover existing CLI sessions on restart.

Context compaction

Handled via context-grooming.md and context-transfer.md prompt templates — agent-executed on demand.

Max concurrent agents

Unlimited (no cap stated).

08

Ui Cli Surface

Maestro (RunMaestro) — UI & CLI Surface

Desktop application

Maestro is an Electron desktop app — the primary interface.

CLI binary: maestro-cli

maestro-cli agents list           # List agents (human-readable)
maestro-cli agents list --jsonl   # Machine-readable JSONL output
maestro-cli groups list           # List Group Chat configurations
maestro-cli playbook run <file>   # Execute a playbook (headless)

The CLI enables cron/CI integration: maestro-cli playbook run can run unattended playbooks from shell scripts or scheduled jobs.

Key UI features

Feature Notes
Multi-agent dashboard Unlimited sessions with status indicators
Group Chat window Moderator AI + @mention participant routing
Git integration Branch display, diff viewer, commit logs, worktree management
File Explorer Syntax highlight, markdown preview, image view, @-mention support
Output Filtering Regex include/exclude on agent output
Usage Dashboard Token/cost heatmaps, per-agent analytics (Opt+Cmd+U)
Document Graph Wiki-link visualization of markdown docs
Slash Commands Extensible /command system with template vars and autocomplete
Mobile Remote Built-in web server + QR code, Cloudflare tunnel for remote access
Speakable Notifications TTS when tasks complete
Themes 12 themes
Cost Tracking Real-time per-session and global
Achievements 11 gamification ranks
Keyboard Mastery Usage tracking that rewards shortcut learning

Keyboard shortcuts (sample)

Shortcut Action
Cmd+K Quick Actions palette
Cmd+N New Agent
Cmd+J Switch AI/Terminal
Cmd+[ / Cmd+] Previous/Next Agent
Opt+Cmd+U Usage Dashboard

Observability

  • Session history JSON per agent (file-based audit)
  • Usage Dashboard with CSV export
  • Output Filtering with regex for log inspection
  • No structured JSONL replay capability at the platform level

IDE integration

None — standalone Electron app.

Related frameworks

same archetype · same primary tool · same memory type

Goose (Block/AAIF) ★ 46k
A12 UI passthrough

General-purpose AI agent (not just code) with security-first tool inspection, recipe-based shareable configurations, and 15+ LLM…

Vibe Kanban ★ 27k
A12 UI passthrough

Eliminate the overhead of planning, switching between agent terminals, and reviewing diffs by providing a single web dashboard…

1Code ★ 5.5k
A12 UI passthrough

Cursor-like desktop experience for Claude Code and Codex with cloud background agents, event-driven automations, and a full…

Crystal (stravu) ★ 3.1k
A12 UI passthrough

Manage multiple parallel AI coding sessions in isolated git worktrees from a single desktop GUI.

AgentsMesh ★ 2.1k
A12 UI passthrough

Multi-tenant workforce platform that gives every team member a squad of AI coding agents coordinated through channels, pod…

Open Cowork ★ 1.4k
A12 UI passthrough

Makes Claude Code accessible to knowledge workers on Windows/macOS with one-click install, VM sandbox, document skills, and IM…