Skip to content
Back to search

ai-maestro

SkillWorks with Claude CodeGitHub

AI Agent Orchestrator with Skills System - Give AI Agents superpowers: memory search, code graph queries, agent-to-agent messaging. Manage Claude, Codex or any AI Agent from one dashboard. Move Agents between computers and locations

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/23blocks-OS/ai-maestro with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/23blocks-OS/ai-maestro'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/23blocks-os-ai-maestro/badge.svg)](/listings/23blocks-os-ai-maestro)

HTML

<a href="/listings/23blocks-os-ai-maestro"><img src="/api/listings/23blocks-os-ai-maestro/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

This installs everything you need: - AI Maestro dashboard and service - Agent messaging system (AMP) - Claude Code plugin with 5 skills and 32 CLI scripts

**Time:** 5-10 minutes · **Requires:** Node.js 18+, tmux · *Optional:* Claude Code 2.1.287+ for the [inbox mod](docs/CLAUDE-CODE-MODS.md)

<details> <summary>Windows (WSL2) / Linux notes</summary>

**Windows:** Install WSL2 first (PowerShell as Administrator, then restart), then open **Ubuntu** from the Start menu and run the curl command there:

wsl --install

New to WSL? WSL is a Linux system with its own disk, so its home folder starts empty. Keep agents there (`~/agents/<name>`, the default), not in `C:\` folders, which are much slower from WSL. Open their files from Windows at `\\wsl.localhost\Ubuntu\home\<you>\agents`. [Windows in 5 minutes](./docs/WINDOWS-INSTALLATION.md#windows-in-5-minutes-read-this-first) · [Full Windows guide](./docs/WINDOWS-INSTALLATION.md)

**Linux:** Ensure build tools are installed: `sudo apt install tmux build-essential` </details>

<details> <summary>Manual install</summary>

git clone https://github.com/23blocks-OS/ai-maestro.git
cd ai-maestro
yarn install
yarn dev

See [QUICKSTART.md](./docs/QUICKSTART.md) for detailed setup options. </details>

Dashboard opens at `http://localhost:23000`

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 533 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="./docs/logo-constellation.svg" alt="AI Maestro Logo" width="120"/>
  3. # AI Maestro
  4. *I was running 35 AI agents across multiple terminals and became the human mailman between them. So I built AI Maestro.*
  5. **The OS for AI-first organizations — orchestrate any AI agent with persistent memory, agent-to-agent messaging, and multi-machine support.**
  6. [![Version](https://img.shields.io/badge/version-0.106.131-blue)](https://github.com/23blocks-OS/ai-maestro/releases)
  7. [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20(WSL2)-lightgrey)](https://github.com/23blocks-OS/ai-maestro)
  8. [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
  9. [![GitHub Stars](https://img.shields.io/github/stars/23blocks-OS/ai-maestro?style=social)](https://github.com/23blocks-OS/ai-maestro)
  10. ![AI Maestro Dashboard](./docs/images/aiteam-web.png)
  11. **[Website](https://getaimaestro.com)** · **[Docs](https://aimaestro.sh)** · [Blog](https://getaimaestro.com/blog/)
  12. [Quick Start](#quick-start) · [Features](#features) · [Skills](#skills) · [Protocols](#protocols) · [Documentation](#documentation) · [Contributing](./CONTRIBUTING.md)
  13. </div>
  14. ---
  15. ## The Story
  16. I gave an AI agent a real task — not autocomplete, a real engineering problem. It checked the code, read the logs, queried the database, and came back with the answer. That was the moment. *This thing can actually work.*
  17. Within a week I was running 35 agents across terminals. They were productive, but they couldn't talk to each other. I became the human message bus — copying context from one terminal, pasting into another. I was the bottleneck in my own AI team.
  18. **So I built AI Maestro** — one dashboard to see every agent, on every machine, with persistent memory and direct agent-to-agent communication. Today I run 80+ agents across multiple computers, building real companies with them every day.
  19. **What makes this different:**
  20. - **Works with the agents you already use** — Claude Code, Codex and Grok Build get launch, chat history, status and approval cards. Pi, OpenClaw and GitHub Copilot CLI launch from AI Maestro and run in the terminal tab, as does any other terminal agent. [What each one supports](./docs/AGENT-PROGRAMS.md). We don't lock you in.
  21. - **Multi-machine from day one** — Peer mesh network with no central server. Nobody else does this.
  22. - **Agents that communicate** — The Agent Messaging Protocol (AMP) lets agents coordinate directly. You orchestrate, they collaborate.
  23. - **Yours, entirely** — MIT licensed. No account, no telemetry, no per-seat pricing, no hosted tier we upsell you to. Your code and your agents stay on your machines.
  24. ---
  25. ## See it
  26. <p align="center">
  27. <img src="./docs/images/home.png" alt="The AI Maestro dashboard: six agents with role, company and live status (Working, Needs you, Ready), and the header pages" width="900"/>
  28. </p>
  29. *One dashboard for every agent: who is working, who needs you, who is ready. The header opens the extra pages (Teams, Org, Matrix, Attention, Zoom).*
  30. | | |
  31. |---|---|
  32. | <a href="./docs/images/zoom-wall.jpg"><img src="./docs/images/zoom-wall.jpg" alt="Zoom view: every agent as a card with photo, status, role and tags" width="440"/></a><br/>**Zoom.** Every agent at a glance, with photo, status, role and tags. | <a href="./docs/images/agent-profile.jpg"><img src="./docs/images/agent-profile.jpg" alt="Agent profile with identity, program, model, tags and commits" width="440"/></a><br/>**Agent profile.** Name, role, picture, program, model, tags and the commits an agent made. |
  33. | <a href="./docs/images/matrix.png"><img src="./docs/images/matrix.png" alt="The Matrix: open cards in four Eisenhower squares across all agents, with due badges and co-owners" width="440"/></a><br/>**Matrix.** Every open card in four squares, across agents and hosts. Due dates and co-owners show on the card. | <a href="./docs/images/attention.png"><img src="./docs/images/attention.png" alt="The Attention page: overdue cards, cards in review, cards waiting on you and agents that need you" width="440"/></a><br/>**Attention.** What needs you: overdue cards, work waiting on you, agents asking a question. |
  34. | <a href="./docs/images/card-detail.jpg"><img src="./docs/images/card-detail.jpg" alt="Card detail with due date, where the card came from and its owners" width="440"/></a><br/>**Card detail.** Due date, several owners and where the card came from. | <a href="./docs/images/team-kanban.png"><img src="./docs/images/team-kanban.png" alt="A team meeting with agent tiles and a Kanban board" width="440"/></a><br/>**Team meeting.** A war room: agent tiles beside a shared Kanban board. |
  35. | <a href="./docs/images/secrets-card.png"><img src="./docs/images/secrets-card.png" alt="A card in the chat where an agent asks for a credential, with a masked field" width="440"/></a><br/>**Secrets.** An agent asks for a credential; you type it into a masked field in the chat; the agent uses it by name and never sees the value. | <a href="./docs/images/canvas-page.png"><img src="./docs/images/canvas-page.png" alt="A canvas page an agent generated, with a table and Approve and Hold buttons" width="440"/></a><br/>**Canvas.** An agent draws an interactive page in the dashboard; your click goes back to it as an action. |
  36. | <a href="./docs/images/chat-cards.png"><img src="./docs/images/chat-cards.png" alt="Chat with a question card and an approval card" width="440"/></a><br/>**Chat.** Questions and approvals arrive as cards you answer with one click. | <a href="./docs/images/commit-trace.jpg"><img src="./docs/images/commit-trace.jpg" alt="Commit to session: find which agent session made a commit" width="440"/></a><br/>**Commit to session.** Find which agent session made a commit. |
  37. On a phone: <a href="./docs/images/mobile-matrix.png">Matrix</a> · <a href="./docs/images/mobile-home.png">home</a> · <a href="./docs/images/mobile-board.png">board</a>.
  38. **Short videos** (click to play):
  39. [<img src="./docs/videos/header-pages-tour.jpg" alt="Tour of the header pages" width="210"/>](./docs/videos/header-pages-tour.mp4)
  40. [<img src="./docs/videos/cli-card-appears-on-matrix.jpg" alt="A card created from the command line appears on the Matrix" width="210"/>](./docs/videos/cli-card-appears-on-matrix.mp4)
  41. [<img src="./docs/videos/canvas-action-reaches-agent.jpg" alt="A canvas click reaches the agent" width="210"/>](./docs/videos/canvas-action-reaches-agent.mp4)
  42. [<img src="./docs/videos/multi-agent-kanban-card-moves.jpg" alt="Cards move across the Kanban while agents work" width="210"/>](./docs/videos/multi-agent-kanban-card-moves.mp4)
  43. [<img src="./docs/videos/secret-request-and-store.jpg" alt="An agent asks for a secret and you store it" width="210"/>](./docs/videos/secret-request-and-store.mp4)
  44. *Screens are from a demo company ("Northwind Labs"); the multi-agent run uses scripted agents.*
  45. ---
  46. ## The Mental Model
  47. **AI Maestro is an operating system for an AI-first company.** Not a task runner — a place where a standing team works.
  48. An agent here is closer to an **employee** than to a job. It has a name, a face, a memory that survives the session, an inbox — and it **owns** something: a product, a repository, a process, a customer. Its memory and code graph are indexed against what it owns, which is why it gets better at that thing over months rather than starting cold every morning.
  49. Because agents own things, **they don't share a working copy.** Two agents that need the same repository each clone it, work on their own branch, and integrate through git — push, pull request, review, merge — exactly like two engineers on a team.
  50. That's deliberate, and it follows from the one thing that defines this product: **your agents run on different machines.** A shared checkout needs a shared filesystem. Git worktrees — the isolation primitive the single-machine agent IDEs are built on — are several working directories over **one `.git` store on one disk**, so they stop working the moment your backend agent is on a Linux box and your iOS agent is on a Mac. A clone is the only primitive that survives the move. It's why transferring an agent to another host clones its repos to the destination: an agent's repositories travel with the agent.
  51. [The full model →](./docs/CONCEPTS.md#agent-ownership)
  52. ---
  53. ## Quick Start
  54. **Step 1. Get the iPhone app** to run your agents from your phone.
  55. **[Coming soon on the App Store](https://getaimaestro.com/iphone.html)**. Free for 30 days, then $19.99 once; it funds AI Maestro.
  56. **Step 2. Install AI Maestro** on the computer where your agents run:
  57. ```bash
  58. curl -fsSL aimaestro.sh/install | bash
  59. ```
  60. This installs everything you need:
  61. - AI Maestro dashboard and service
  62. - Agent messaging system (AMP)
  63. - The AI Maestro plugin for Claude Code: [14 skills](#skills) and their CLI scripts, plus the `aim-secret` and `safe-psql` helpers
  64. **Time:** 5-10 minutes · **Requires:** Node.js 24, tmux, and **4 GB of RAM** to build (or 2 GB plus swap; once built it runs in a few hundred MB) · *Optional:* Claude Code 2.1.287+ for the [inbox mod](docs/CLAUDE-CODE-MODS.md)
  65. <details>
  66. <summary>Windows (WSL2) / Linux notes</summary>
  67. **Windows:** Install WSL2 first (PowerShell as Administrator, then restart), then open **Ubuntu** from the Start menu and run the curl command there:
  68. ```powershell
  69. wsl --install
  70. ```
  71. New to WSL? WSL is a Linux system with its own disk, so its home folder starts empty. Keep agents there (`~/agents/<name>`, the default), not in `C:\` folders, which are much slower from WSL. Open their files from Windows at `\\wsl.localhost\Ubuntu\home\<you>\agents`. [Windows in 5 minutes](./docs/WINDOWS-INSTALLATION.md#windows-in-5-minutes-read-this-first) · [Full Windows guide](./docs/WINDOWS-INSTALLATION.md)
  72. **Linux:** Ensure build tools are installed: `sudo apt install tmux build-essential`. On a cloud VM, read the [Linux sizing and deployment guide](./docs/LINUX-DEPLOYMENT.md): the machine to ask for (4 GB RAM, 2 vCPU, 15-25 GB disk), the memory each part uses, and running under pm2.
  73. </details>
  74. <details>
  75. <summary>Manual install</summary>
  76. ```bash
  77. git clone https://github.com/23blocks-OS/ai-maestro.git
  78. cd ai-maestro
  79. yarn install
  80. yarn dev
  81. ```
  82. See [QUICKSTART.md](./docs/QUICKSTART.md) for detailed setup options.
  83. </details>
  84. Dashboard opens at `http://localhost:23000`
  85. **Update** an existing install from its folder (pulls, updates submodules, builds, reinstalls hooks and the plugin, restarts):
  86. ```bash
  87. ./update-aimaestro.sh -y
  88. ```
  89. **Come back to it** without remembering the address: the installer adds an `ai-maestro` command (`ai-maestro open` starts the server if it is down, then opens the dashboard; also `start`, `stop`, `status`) and, on a Mac, an **AI Maestro** app in `~/Applications` you can drag to the Dock. It can also start at login. Chrome and Edge offer "Install app" from the dashboard too. Skip all of it with `--skip-launcher`; remove it with `./scripts/install-launcher.sh --remove`.
  90. ---
  91. ## Features
  92. Every feature was born from running a real AI-first organization. We built them in the order we needed them.
  93. ### One Dashboard
  94. *I had 35 terminals and couldn't tell which was which.*
  95. See and manage all your AI agents in one place. Create agents from the UI with a guided wizard, organize them with smart naming (`project-backend-api` becomes a 3-level tree with auto-coloring), and switch between any agent with a click. Four deployment modes: **tmux** (local), **Docker** (containerized), **AWS EC2** (dedicated instance), and **AWS ECS Fargate** (serverless). Auto-discovers tmux sessions, Docker containers, cloud deployments, and standalone agents.
  96. ### Any Machine
  97. *My Mac Mini was sitting there idle. What if I ran agents on that too?*
  98. A peer mesh network where every machine is equal. Add a computer, it joins the mesh. Every agent on every machine, visible from one dashboard. Use each machine for what it's best at — Mac for iOS builds, Linux for Docker, cloud for heavy compute. **No central server required.**
  99. Worker machines can run headless (`yarn headless`) — the full API and agent runtime with no UI, in about 100MB of RAM. Run the dashboard where you sit; run agents wherever the compute is.
  100. ### Agent Messaging
  101. *I was the mailman — copying messages between agents because they couldn't talk to each other.*
  102. The [Agent Messaging Protocol (AMP)](https://agentmessaging.org) gives your agents email-like communication. Priority levels, message types, cryptographic signatures, and push notifications. Tell your agent *"send a message to backend about the deployment"* — it just works. Agents coordinate directly while you manage the big picture.
  103. **Before AMP:** You copy research from one terminal, paste into another, repeat 50 times a day.
  104. **With AMP:** *"Research agent, send your findings to the writing agent."* Done.
  105. ### Gateways
  106. *A friend in Singapore wanted his agents to talk to mine. But I didn't want to give him access to my network.*
  107. Connect your AI agents to [Slack](https://github.com/23blocks-OS/aimaestro-gateways), Discord, Email, and WhatsApp through organizational gateways. Smart routing (`@AIM:agent-name`), thread-aware responses, and content security with 34 prompt injection patterns detected at the gateway — before any agent sees the message.
  108. ### Persistent Memory
  109. *Every morning, my agents woke up with amnesia.*
  110. **Long-term memory** is a skill you switch on per agent. Every night each agent's conversations become memory: short statements of what it learned, each backed by the passages it came from, and an **entity graph** of the things it works with and how they relate (`runs on`, `depends on`, `stores data in`, `deploys to`), kept current, with ended relations marked. Claude Code deletes transcripts after 30 days; AI Maestro rebuilds that history from the agent's own message index, so months of work become memory instead of disappearing. When a prompt names something, the agent is told what it relates to before it acts, so it can see what a change affects. Knowledge that comes up in more sessions weighs more; secrets are redacted and never stored. [How it works →](docs/LONG-TERM-MEMORY.md)
  111. Alongside it: **Code Graph** (interactive visualization of your entire codebase with delta indexing) and **Documentation** (auto-generated, searchable docs from your code). Agents get smarter the longer they work with you.
  112. ### Chat
  113. *I wanted to answer an agent's question without finding its terminal.*
  114. Talk to an agent in a chat view, on desktop or on your phone. When the agent asks a question or needs an approval, it shows up as a card you can click, and the click sends the same key you would press in the terminal. Claude Code, Codex and Grok Build all work here. [How the chat works →](docs/CHAT-ARCHITECTURE.md)
  115. ### Secrets
  116. *I kept pasting API keys into chats, and the model kept seeing them.*
  117. Agents use a credential without seeing it. `aim-secret` keeps values in a local vault (macOS Keychain, Linux libsecret, or an encrypted file). An agent asks for a secret by name; a card in the chat, with a masked field, lets you store it; the agent then runs commands that use it by name, with the value scrubbed from the output. In Claude Code, the `ai-maestro-secrets` mod asks through a form in the terminal instead. Scrubbing stops accidents, not an agent that wants the value, so use narrowly scoped keys. [Secrets →](docs/SECRETS.md) · [Claude Code mods →](docs/CLAUDE-CODE-MODS.md)
  118. ### Work Coordination
  119. *Talking isn't working. I needed agents to coordinate on actual deliverables.*
  120. Assemble agents into teams, run meetings in split-pane war rooms, and track tasks on a full Kanban board with drag-and-drop, dependencies, and 5 status columns. Cross-machine teams work seamlessly. This is project management for your AI workforce.
  121. Every agent also keeps its own board, and any agent, in any framework, can feed it with the `agent-tasks` skill. A card can carry a **due date**, **several owners** (it shows on each owner's board), a **kind** (task, idea, bug, research) and **where it came from**. Three extra pages, reached from the header and never replacing the main view, read the same cards: the **Matrix** (Eisenhower squares across all agents and hosts), the **Org** view, and **Attention** (agents that need you, cards waiting on you, overdue cards). [Tasks, Matrix and Attention →](docs/TASKS.md)
  122. **World view (beta)** is an experiment: switch it on in Settings → Experiments and the header gets a World button that draws your hosts and organizations as 3D islands with their agents on them, in the live status colours. [World view →](docs/WORLD-VIEW.md)
  123. ### Claude Code Mods
  124. *A Claude Code session with no tmux has nowhere for a message to land.*
  125. Mods are plugins that run inside Claude Code 2.1.287 or later. AI Maestro ships two: an **inbox mod** that shows unread agent messages in the status line and above the prompt, and a **secrets mod** that lets an agent request a credential. AI Maestro itself works with any current Claude Code version. [Details and limits →](docs/CLAUDE-CODE-MODS.md)
  126. ### Canvas
  127. *Sometimes the answer is a form, a chart or an approval, not a paragraph.*
  128. Agents draw interactive HTML pages in the dashboard, and what you click or submit comes back to them as a structured action ([AAP](#protocols)). [Agent actions →](https://aimaestro.sh/agent-actions.html)
  129. ### Scheduled Work
  130. *Some jobs shouldn't wait for me to remember to ask.*
  131. Give an agent its own schedule — morning triage, a nightly dependency check, a Monday report. The timer belongs to the **agent, not the machine**, so a schedule travels with the agent when it moves hosts, and fires when that agent goes idle instead of interrupting it mid-task.
  132. ### Agent Presence
  133. *At 80 agents, they all looked the same.*
  134. Custom avatars, personality profiles, and roles for every agent. When an agent has a face and a job title, you instinctively assign it the right work — just like a real team.
  135. Agents can also **speak and be seen**: a voice pipeline with your choice of TTS provider, and live animated faces that move while the agent talks. Open a call with an agent and it looks back at you. Nobody else is doing this, and once you've reviewed a plan by listening to it on a walk, the terminal feels like a downgrade.
  136. One caveat worth stating plainly: **true lip-sync — mouth movement driven by the actual audio — needs the OpenAI or ElevenLabs voice and an API key.** The default browser voice (`web-speech`) renders straight to your speakers and exposes no audio stream to measure, so the face animates from a synthetic envelope instead. It looks alive; it is not tracking the words. That is a limit of the Web Speech API, not something we plan to work around.
  137. ### Agent Deployment
  138. *One agent on my laptop. Another on EC2. A third on Fargate. All in the same dashboard.*
  139. Four ways to run agents, each for a different need:
  140. | Mode | What | Best For |
  141. |------|------|----------|
  142. | **tmux** | Direct terminal sessions on your machine | Local development, zero setup |
  143. | **Docker** | Containerized agents with resource limits | Isolation, reproducibility, multi-project |
  144. | **AWS EC2** | Dedicated Graviton instance with native install, Nginx + SSL | Always-on agents, SSH access, persistent workloads |
  145. | **AWS ECS Fargate** | Serverless containers, auto-built Docker image | Burst scaling, zero maintenance, pay-per-use |
  146. Cloud agents are Terraform-managed. EC2 installs Node.js, tmux, and AI CLIs directly on ARM64 hardware (no Docker overhead). ECS auto-builds your Docker image, pushes to ECR, and runs on Fargate. Both deploy with one command from the dashboard or CLI.
  147. ```bash
  148. # EC2: dedicated instance with SSL
  149. aimaestro-agent.sh create my-api --ec2 \
  150. --domain api.example.com --ssl-email admin@example.com --key-name my-key
  151. # ECS Fargate: serverless (auto-builds image)
  152. aimaestro-agent.sh create worker --ecs
  153. ```
  154. ---
  155. ## Meet Lola — Your First Hire
  156. Every AI-first organization starts with one agent. **Lola** is yours — a batteries-included Chief of Staff framework built for AI Maestro. She handles email triage, semantic memory, task management, and content security out of the box. Install the platform, deploy Lola, and you have your first employee on day one.
  157. ```bash
  158. # Clone and deploy Lola on AI Maestro
  159. git clone https://github.com/23blocks-OS/lolabot.git
  160. cd lolabot && ./setup.sh
  161. ```
  162. **The LolaBot Ecosystem:**
  163. - **[LolaBot Framework](https://github.com/23blocks-OS/lolabot)** — Open-source agent framework. Build your own Lola.
  164. - **[lolabots.com](https://lolabots.com)** — The LolaBot Factory. Pre-built agent templates, one-click deploy.
  165. [Learn more about Lola →](https://github.com/23blocks-OS/lolabot)
  166. ---
  167. ## The Agent Ecosystem
  168. Every agent is built from these dimensions:
  169. | | Dimension | What | Where |
  170. |-|-----------|------|-------|
  171. | **WHO** | Personality | Domain expertise, workflows, deliverables | [Agent Library](https://github.com/msitarzewski/agency-agents) (150+) |
  172. | **HOW** | Capabilities | Skills, scripts, CLI tools, Canvas | [Plugin Builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  173. | **TRUST** | Identity | Cryptographic keys, OAuth tokens | [AID](https://agentids.org) |
  174. | **TALK** | Communication | Agent-to-agent messaging | [AMP](https://agentmessaging.org) |
  175. | **ACT** | Actions | Clicks and forms from agent-drawn pages | [AAP](https://agentactions.org) |
  176. | **BE THERE** | Devices | Real devices an agent owns and jumps between | [ADP](https://agentdevices.org) |
  177. See [Skills](#skills) and [Protocols](#protocols) below.
  178. AI Maestro is the stage. Pick personalities, give them skills, and run them from one dashboard.
  179. [Read the full ecosystem guide →](./docs/ECOSYSTEM.md)
  180. ---
  181. ## Skills
  182. The AI Maestro plugin (version 1.18.0) carries 14 skills in the open [Agent Skills Standard](https://agentskills.io/specification) format. An agent loads a skill when its description matches the task.
  183. | Skill | What it does | Source |
  184. |---|---|---|
  185. | `memory-search` | Search what the agent learned in past sessions, and what depends on an entity | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  186. | `docs-search` | Look up signatures and APIs in the generated docs | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  187. | `graph-query` | Callers, dependencies and blast radius from the code graph | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  188. | `ai-maestro-agents-management` | Create, rename, hibernate, wake and delete agents | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  189. | `planning` | Persistent plan, findings and progress files for long tasks | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  190. | `agent-tasks` | The agent's own task board: quadrant, waiting, parked ideas, origin, due dates, shared cards, and `import` of an existing list | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  191. | `aim-secret-management` | Use a credential without seeing it; ask the user to store one | [plugin builder](https://github.com/23blocks-OS/ai-maestro-plugins) |
  192. | `agent-messaging` | Signed messages between agents (AMP) | [agentmessaging/claude-plugin](https://github.com/agentmessaging/claude-plugin) |
  193. | `agent-identity` | Sign in with an Ed25519 identity and OAuth 2.0 tokens (AID) | [agentmessaging/agent-identity](https://github.com/agentmessaging/agent-identity) |
  194. | `agent-actions` | Interactive pages in the dashboard and their actions (AAP) | [agentmessaging/agent-actions](https://github.com/agentmessaging/agent-actions) |
  195. | `agent-files` | Share files across hosts through an AFP space | [agentmessaging/agent-files](https://github.com/agentmessaging/agent-files) |
  196. | `agentic-sql` | Read-only SQL against real databases through `safe-psql`; changes data only through `safe-psql-write`, after a person approves each change | [23blocks-OS/agentic-sql](https://github.com/23blocks-OS/agentic-sql) |
  197. | `agentic-support` | Numbered support cases with a written trail, and runbooks | [23blocks-OS/agentic-support](https://github.com/23blocks-OS/agentic-support) |
  198. | `agentic-seo` | SEO audit and implementation for websites | [23blocks-OS/agentic-seo](https://github.com/23blocks-OS/agentic-seo) |
  199. The installer and updater set up the helpers the skills need (`aim-secret`, `safe-psql`). To add only the plugin to Claude Code:
  200. ```
  201. /plugin marketplace add 23blocks-OS/ai-maestro-plugins
  202. /plugin install ai-maestro@ai-maestro-plugins
  203. ```
  204. Pick your own set with the [plugin builder](./plugin/README.md). More on the [skills page](https://aimaestro.sh/skills.html); how we keep them good is in [SKILLS-QUALITY.md](./docs/SKILLS-QUALITY.md).
  205. ---
  206. ## Protocols
  207. AI Maestro uses the open protocols under [github.com/agentmessaging](https://github.com/agentmessaging): four today, and a fifth, [ADP](https://agentdevices.org), for devices, on its way. Each works without the others.
  208. | Protocol | Covers | Specification |
  209. |---|---|---|
  210. | **AMP** — Agent Messaging Protocol | Signed messages between agents, local or federated | [agentmessaging.org](https://agentmessaging.org) |
  211. | **AID** — Agent Identity | Ed25519 agent identity and OAuth 2.0 tokens | [agentids.org](https://agentids.org) |
  212. | **AAP** — Agent Actions Protocol | Actions from agent-drawn pages back to the agent | [agentactions.org](https://agentactions.org) |
  213. | **AFP** — Agent Files Protocol | Files shared by reference through S3-compatible storage | [agentmessaging/agent-files](https://github.com/agentmessaging/agent-files) |
  214. | **ADP** — Agent Device Protocol | Agents own and use real devices: signed, approved on the device, no cloud. Controller in progress | [agentdevices.org](https://agentdevices.org) |
  215. [Protocols page](https://aimaestro.sh/protocols.html) · [AID, AMP and AAP mapped onto the Poppy draft](./docs/AID-POPPY-MAPPING.md) (a design note, nothing implemented) · [AMP outbox design](./docs/AMP-OUTBOX-DESIGN.md) (a proposal, not built)
  216. ---
  217. ## Who Is This For
  218. **Founders building AI-first organizations.** You're the CEO, your agents are the team. Solo operators, agency owners, and anyone running a business where AI agents do the work and you drive the strategy. Start with Lola, add specialists, scale your AI workforce.
  219. **Developers running multiple AI agents.** If you have 3+ agents and you're switching between terminals, losing context, and playing messenger — this is for you. Works with Claude Code, Codex, Grok Build, or any terminal-based AI.
  220. **Teams coordinating AI-assisted work.** Multiple developers, multiple agents, multiple machines. One dashboard. Agent-to-agent messaging replaces you as the bottleneck.
  221. **Creators and operators** who want to connect AI agents to the outside world through Slack, Discord, or Email — without exposing their infrastructure.
  222. ---
  223. <details>
  224. <summary><b>Screenshots</b></summary>
  225. <div align="center">
  226. <img src="./docs/images/aimaestro-mobile.png" alt="Mobile View" width="280"/>
  227. <img src="./docs/images/aimaestro-sidebar.png" alt="Sidebar" width="280"/>
  228. </div>
  229. **Code Graph** — Interactive codebase visualization
  230. ![Code Graph](./docs/images/code_graph01.png)
  231. **Agent Inbox** — Direct agent-to-agent messaging
  232. ![Agent Messaging](./docs/images/agent-inbox.png)
  233. </details>
  234. ---
  235. ## Documentation
  236. The documentation site is **[aimaestro.sh](https://aimaestro.sh)** (install and guides). The project home, the iPhone app and the blog are at **[getaimaestro.com](https://getaimaestro.com)**. The Markdown files below are the same guides in this repository.
  237. **New here?**
  238. - [Quick Start Guide](./docs/QUICKSTART.md) — Get up and running
  239. - [Core Concepts](./docs/CONCEPTS.md) — Understand how it works
  240. - [Use Cases](./docs/USE-CASES.md) — Real examples of what people build
  241. **Going deeper:**
  242. - [Multi-Machine Setup](./docs/SETUP-TUTORIAL.md) · [Network Access](./docs/NETWORK-ACCESS.md)
  243. - [Cloud Deployment (AWS)](https://aimaestro.sh/cloud-aws.html) · [Docker Agents](https://aimaestro.sh/docker-local.html)
  244. - [Agent Messaging Guide](./docs/AGENT-MESSAGING-GUIDE.md) · [Architecture](./docs/AGENT-COMMUNICATION-ARCHITECTURE.md)
  245. - [Chat Architecture](./docs/CHAT-ARCHITECTURE.md) — how messages reach an agent, and how questions come back
  246. - [Intelligence Guide](./docs/AGENT-INTELLIGENCE.md) · [Code Graph](./docs/images/code_graph01.png) · [Long-term memory](./docs/LONG-TERM-MEMORY.md)
  247. - [Secrets](./docs/SECRETS.md) — agents use a credential without seeing it
  248. - [Claude Code mods](./docs/CLAUDE-CODE-MODS.md) — inbox and secrets mods, and Claude Code versions
  249. - [Agent programs](./docs/AGENT-PROGRAMS.md) — what Claude Code, Codex and Grok Build each support
  250. - [Operations Guide](./docs/OPERATIONS-GUIDE.md)
  251. **Troubleshooting:**
  252. - [Common Issues](./docs/TROUBLESHOOTING.md) · [Security](./SECURITY.md) · [Windows Installation](./docs/WINDOWS-INSTALLATION.md)
  253. **Open Protocols:**
  254. - [AMP](https://agentmessaging.org) · [AID](https://agentids.org) · [AAP](https://agentactions.org) · [AFP](https://github.com/agentmessaging/agent-files) · [ADP](https://agentdevices.org)
  255. - Design notes: [AID, AMP and AAP on the Poppy draft](./docs/AID-POPPY-MAPPING.md) · [AMP outbox (proposal)](./docs/AMP-OUTBOX-DESIGN.md)
  256. **Extending:**
  257. - [Plugin Development](./plugin/README.md) · [API Reference](./docs/AGENT-COMMUNICATION-ARCHITECTURE.md) · [Ecosystem Guide](./docs/ECOSYSTEM.md)
  258. ---
  259. ## What's Next
  260. - **Create an agent from a repo URL** — clone and staff it in one step, instead of cloning by hand and pointing an agent at the folder
  261. - Agent search and filtering across the entire mesh
  262. - Agent playback — time-travel through agent sessions
  263. - Performance analytics dashboard
  264. See the full [roadmap](https://github.com/23blocks-OS/ai-maestro/issues).
  265. ---
  266. ## Contributing
  267. We love contributions. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
  268. - [Report a bug](https://github.com/23blocks-OS/ai-maestro/issues)
  269. - [Request a feature](https://github.com/23blocks-OS/ai-maestro/issues/new?labels=enhancement)
  270. ### Contributors
  271. AI Maestro is better because of people outside the team who hit something, read
  272. the source, and sent a fix. In order of arrival:
  273. - **[@Emasoft](https://github.com/Emasoft)** — a consolidated fix across memory,
  274. terminal, installers, skills and the API covering 65+ issues, plus CI repairs
  275. for the installer workflow and the agent-cli skill check. The single largest
  276. outside contribution to this project.
  277. - **[@dwzrd86](https://github.com/dwzrd86)** (Darius Davis) — Ubuntu 24.04 support
  278. and crash resilience, and the Phase 5 work behind the Search, Export and
  279. Playback tabs: hooks, UI scaffolding, and the integration into the main page.
  280. - **[@Tanariel](https://github.com/Tanariel)** — `C-m` instead of `Enter` for tmux
  281. `send-keys`, which is still how every message reaches an agent today, and a fix
  282. stopping undefined values from overwriting task fields on update.
  283. - **[@meichuanyi](https://github.com/meichuanyi)** — the FAQ section, which is the
  284. first thing many people read.
  285. - **[@CamiloCaceres](https://github.com/CamiloCaceres)** (Camilo Caceres) — found
  286. that reading transcripts and running the embedding model inside the server froze it
  287. on a Mac with 24 agents, and fixed both: transcripts are streamed, and the model runs
  288. in its own bounded process (0.93.2 and 0.93.3, [measured on Linux](./docs/LINUX-DEPLOYMENT.md)).
  289. - **[@weliu](https://github.com/weliu)** (Wenfeng Liu) — corrected the pm2 start
  290. command to use `ecosystem.config.js`.
  291. - **[@nodoyuna](https://github.com/nodoyuna)** (Javier Moya, [jaak.ai](https://jaak.ai))
  292. — found that the installer reported success over an install that could not
  293. start, traced it to an early return that made the existing repair unreachable,
  294. and sent a tested fix ([#453](https://github.com/23blocks-OS/ai-maestro/pull/453)).
  295. [Full list on GitHub →](https://github.com/23blocks-OS/ai-maestro/graphs/contributors)
  296. We built this because one of us was running 35 agents across terminals and had
  297. become the human message bus between them. It solved our problem. That it solves
  298. yours too is the best thing that has happened to this project — and a patch from
  299. someone who hit a rough edge and read the source is the most useful thing we can
  300. receive. [Open a PR](./CONTRIBUTING.md).
  301. <details>
  302. <summary><b>Acknowledgments</b></summary>
  303. Built with [Next.js](https://nextjs.org/), [xterm.js](https://xtermjs.org/), [CozoDB](https://www.cozodb.org/), [ts-morph](https://ts-morph.com/), [tmux](https://github.com/tmux/tmux), and [Claude Code](https://claude.ai).
  304. </details>
  305. ---
  306. ## License
  307. MIT — see [LICENSE](./LICENSE). Free for any purpose, including commercial.
  308. ---
  309. <div align="center">
  310. **Made with love in Boulder (USA), Roma (Italy), and many other cool places**
  311. [Juan Pelaez](https://x.com/jkpelaez) · [23blocks](https://23blocks.com)
  312. *Built by AI Agents with Humans in the driver seat — for AI-first organizations, AI-enabled humans, and autonomous agents*
  313. [Star us on GitHub](https://github.com/23blocks-OS/ai-maestro)
  314. </div>
  315. ## FAQ
  316. **Do I need to use Claude Code?**
  317. No. Claude Code, Codex and Grok Build get first-class support (launch, chat, status, approval cards), and any other terminal agent runs in the terminal tab. See [what each one supports](./docs/AGENT-PROGRAMS.md).
  318. **Does it work on Linux / Windows?**
  319. Yes. macOS and Linux natively. Windows via WSL2 — see the [Windows guide](./docs/WINDOWS-INSTALLATION.md).
  320. **Can agents on different machines talk to each other?**
  321. Yes. The [Agent Messaging Protocol (AMP)](https://agentmessaging.org) handles cross-machine messaging with cryptographic signatures and push notifications. No central server required.
  322. **What are AID, AAP and AFP?**
  323. [AID](https://agentids.org) (Agent Identity) gives each agent a portable cryptographic identity. [AAP](https://agentactions.org) (Agent Actions Protocol) carries a click or form submit from an agent-drawn page back to the agent. [AFP](https://github.com/agentmessaging/agent-files) (Agent Files Protocol) shares files across hosts by reference. Together with [AMP](https://agentmessaging.org), they are the open protocols AI Maestro implements. See [Protocols](#protocols).
  324. **What is the Canvas skill?**
  325. The `agent-actions` skill lets an agent draw interactive HTML pages (dashboards, charts, forms, approvals) in the AI Maestro dashboard and handle what you click or submit. It ships in the plugin.
  326. **How is this different from just using tmux?**
  327. tmux gives you terminals. AI Maestro gives you an organization — persistent memory, agent-to-agent messaging, team coordination, Kanban boards, multi-machine mesh, cloud deployment, and gateway integrations. tmux is the foundation; AI Maestro is the building.
  328. **What is LolaBot?**
  329. [LolaBot](https://github.com/23blocks-OS/lolabot) is an open-source agent framework — a batteries-included Chief of Staff that handles email, memory, tasks, and security. The [LolaBot Factory](https://lolabots.com) offers pre-built agent templates for one-click deployment.
  330. **What does it cost?**
  331. Nothing. MIT licensed, free for any purpose including commercial — no seats, no usage fees, no paid tier. You bring your own agent subscriptions (Claude Code, Codex, Grok Build, whatever you already pay for) and AI Maestro just runs them. Note that some tools in this space are *source-available* rather than open source, under licenses that forbid offering them as a service; MIT has no such restriction.
  332. **Do you collect telemetry?**
  333. No. No analytics SDK, no account, no login, no phone-home. The only telemetry in the product is the agent metrics shown on your own dashboard, and those post to `localhost:23000` — your machine. Point them at a central collector only if you choose to run one.
  334. **How does this compare to the parallel-agent IDEs?**
  335. Different job, and deliberately so. Tools like Orca, Paseo, Superset and Conductor run several agents on **one repository on one machine**, each in an isolated git worktree, then diff the results so you can merge the best one. It's a disposable fan-out: five attempts at the same task, keep one, throw away four. They're good at it. If that's the workflow you want today, use one of them.
  336. AI Maestro is built for the case after that one — a **standing team** of agents that own things, remember their work, message each other, and run across every machine you have. We don't use worktrees because worktrees can't leave the machine they're on: they're several working directories over one `.git` store on one disk. Our agents each clone what they own and integrate through pull requests, like a human team, which is the only model that works when the backend agent is on Linux and the iOS agent is on a Mac. See [the mental model](#the-mental-model).
  337. **Can I run several agents on the same repository?**
  338. Yes — give each one its own clone. Backend owns the API, frontend owns the web app, infra owns the Terraform, even inside a monorepo. They coordinate over AMP and merge through git. For a large repo, `git clone --filter=blob:none` or `--reference` to a local mirror keeps the disk cost down. And an individual agent is free to use `git worktree` inside its own clone — worktrees are a fine tool *within* an agent, just not how we isolate agents *from each other*.
  339. **Is there a hosted / cloud version?**
  340. Not yet. AI Maestro runs on your machines. You own your data, your agents, and your infrastructure.
  341. **How do I add more agents?**
  342. Create them from the dashboard UI, the CLI (`aimaestro-agent.sh create`), or just start a new tmux session — AI Maestro auto-discovers it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.