catlog22/maestro-flow

Maestro‑Flow – Intent‑driven multi‑agent workflow orchestration

What it is – A TypeScript/Node.js framework that lets you describe what you want to achieve in natural language and automatically builds, schedules, and runs a chain of AI agents to carry out the whole development lifecycle (brainstorm → plan → code → test → review → deploy). It works with several LLM back‑ends (Claude, Gemini, Codex, Qwen, Grok, etc.) and keeps a persistent knowledge graph so the system gets smarter over time.

---

Core capabilities (as described in the README)

Capability	What it does
Self‑adaptive orchestration	The Ralph engine classifies an intent into one of 40+ predefined command chains and, at each decision node, decides whether to continue, roll back, or insert a repair loop – no YAML files needed.
Cross‑backend scheduling	Within a single workflow you can mix agents that call Claude, Codex, Gemini, Qwen, OpenCode, Grok, etc., using four coordination modes: Delegate (async delegation), Team (role‑based collaboration), Wave (parallel dependencies), Swarm (ant‑colony style exploration).
Knowledge self‑enhancement	Patterns, pitfalls and decisions discovered during runs are automatically stored as Spec and Knowhow entries. A hook system injects this knowledge into later prompts, making future runs more efficient.
Long‑term self‑correction	The Odyssey command runs hour‑scale autonomous loops that keep re‑evaluating results until acceptance criteria are met, persisting new knowledge each cycle.
Precise search	Built‑in literal search (via ripgrep) and optional semantic re‑ranking (BM25 → embeddings) let you locate code snippets quickly; the search respects .gitignore, .maestroignore and other safety limits.

---

Installation (quick steps from the README)

# Global install of the CLI (requires Node ≥22.19)
npm install -g maestro-flow@0.5.82

# Interactive component selection
maestro install

You also need at least one host CLI such as Claude Code (default) or Grok Build; optional adapters for Codex CLI and agy CLI are available.

---

Typical workflow

1. Speak your intent – e.g. /maestro-ralph "实现 OAuth2 认证，支持 refresh token"
2. Ralph builds a chain – analyze → plan → execute → verify → review → test (auto‑inserts debug/fix loops on failure).
3. Run the session – maestro session open, then maestro run next repeatedly until the session is completed.
4. Knowledge accumulation – Any discovered pattern is stored and later injected via hooks.
5. Long‑run mode – For big refactors use /maestro-odyssey <intent> --mode <debug|planex|improve|…> which loops until the defined acceptance criteria are satisfied.

---

Key concepts & terminology

• Ralph – the decision‑making engine that maps natural‑language intents to command chains.
• Odyssey – a long‑duration autonomous loop for heavy‑weight debugging, security audits, UI inspections, etc.
• Decision node – a checkpoint where the engine evaluates results and decides the next action.
• Spec / Knowhow – persisted knowledge artifacts that are automatically added to future prompts.
• Hooks – 17 predefined extension points where stored knowledge can be injected into an agent’s prompt.
• MCP (Model Context Protocol) – the protocol used for communication between the CLI and the LLM back‑ends.

---

Example commands

# Simple intent → full pipeline (default quality mode)
/maestro "添加用户资料页"

# Direct run of a single task without full pipeline
/maestro-companion "修正 README 拼写"

# Search for a literal string in the repo
maestro search "Authorization: Bearer" --exact --json

# Run a long‑term security audit
/maestro-odyssey "安全审计整个项目" --mode security

---

Documentation & learning resources (as listed)

• Quick‑start guide – installation and first workflow.
• Ralph engine guide – decision logic, quality modes, session handling.
• Command reference – 64 slash commands and 35+ CLI commands.
• Knowledge‑management guide – how Specs, Knowhow and the SQLite knowledge graph work.
• Advanced design docs – multi‑agent coordination, overlay extensions, worktree parallelism, MCP tools, search system, MaestroGraph architecture, etc.

---

Project size & tech stack

• Code – 333 TypeScript files (~80 k lines).
• CLI – built with Commander.js, MCP SDK, better‑sqlite3, web‑tree‑sitter.
• Dashboard – React 19 + Zustand + Tailwind CSS, served via Hono/Vite.
• Agents – 23 definitions, 45 skill packs, 64 slash commands.
• Templates & workflows – 92 JSON templates, 115 workflow definitions.

---

How it compares to similar tools (summary from the README)

Tool	Focus	Maestro‑Flow’s edge
Superpowers	Agent skill framework (markdown‑only)	Full‑runtime orchestration, cross‑backend scheduling, persistent KG
OpenSpec	Spec‑driven development	Intent‑driven automatic chain generation, dynamic decision nodes
Trellis	Multi‑platform agent fixtures	Long‑running autonomous loops (Odyssey) and self‑correcting pipelines

---

Who maintains it

Created and maintained by @catlog22 (GitHub user catlog22). The repo includes a WeChat group for community discussion and is released under the MIT license.

---

Bottom line

Maestro‑Flow is a production‑grade, intent‑driven orchestration layer that lets developers harness multiple LLM agents to automate the entire software development lifecycle, while continuously learning from each run. It is a genuine open‑source project aimed at the frontier of AI‑augmented software engineering.