Maestro-Flow CLI
Maestro-Flow builds a chain from analysis to tests for a goal and runs Claude Code, Codex, Gemini and other agents through it
- 575 ★ on the repository
- Last commit
Broad access
Why this level
- Multi-hour autonomous Odyssey loops and the `-y` mode write code and run commands without confirmation
- Installation places commands, hooks and instructions in the directories of Claude Code and other agents
- One flow starts several paid agents at once and spends their quotas
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/maestro-flowDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Multi-hour autonomous Odyssey loops and the `-y` mode write code and run commands without confirmation
- Installation places commands, hooks and instructions in the directories of Claude Code and other agents
- One flow starts several paid agents at once and spends their quotas
This is third-party code. Review the repository files before installing.
What it does
Maestro-Flow is an npm package that orchestrates development across several coding agents for a stated goal. In Claude Code you write `/maestro-ralph "implement OAuth2 with refresh tokens"`, and the Ralph engine detects the project stage and builds a chain of analyze, plan, execute, verify, review and test. At decision points it proceeds, falls back or inserts a fix loop. There are more than forty chain types. Install with `npm install -g maestro-flow@0.5.82`, then `maestro install` to pick components. One workflow mixes the CLIs of different agents: Claude, Codex, Gemini, Qwen, OpenCode and Grok. Coordination has four modes: Delegate hands off a task asynchronously, Team splits roles, Wave runs independent steps in parallel and Swarm explores variants. Three quality modes, `full`, `standard` and `quick`, set the depth of checks. Patterns, pitfalls and decisions found along the way are saved as Spec and Knowhow, and hooks inject them into the next agents' prompts. Odyssey commands run multi-hour self-correcting loops in debug, planex, improve, review, security, defensive and ui modes. The security and defensive modes only read code. `maestro search` searches the project, and the `--exact` flag looks up a string through a bundled ripgrep.
Who it is for. Developers who drive a large task through several agents at once and want analysis, implementation, review and tests to follow a chain while knowledge accumulates between sessions.
Good fit when
- The task is large, like OAuth2 with refresh tokens, and you want the agent to walk through analyze, plan, execute, verify, review and test itself
- Claude Code implements, Codex reviews and Gemini checks the plan: all three work in one flow
- A bug takes hours to find: `/maestro-odyssey --mode debug` loops through analysis, diagnosis and fix until the criteria are met
- A prototype is checked fast in `quick` mode, and `full` with business tests is switched on before a release
- Agent findings such as discovered pitfalls should reach the prompts of later sessions through Spec and Knowhow
Not a fit when
- A one-line fix: `/maestro-companion` or a plain request is enough, a six-stage chain is excessive
- The machine has neither Claude Code nor Grok Build: one of them is required as the host CLI
- Node.js is older than 22.19 and cannot be upgraded
- You want a simple specification and tasks without orchestration: a lighter tool such as OpenSpec fits better
Example request
Install Maestro-Flow and run `/maestro-ralph` for the task: add a user profile page with testsLimitations
- Node.js 22.19 or newer and at least one host CLI are required: Claude Code by default, or Grok Build. Codex CLI and agy CLI are optional extras for multi-agent flows.
- The main README is in Chinese, and an English version lives in `README.en.md`.
- Multi-hour Odyssey loops and several agents at once burn many tokens and subscription quotas. The `-y` flag turns off confirmations.
- The README pins the version in the install command, `maestro-flow@0.5.82`: check it against the latest npm release before installing.
How to disable. Run `npm uninstall -g maestro-flow`. Delete by hand the commands and hooks that `maestro install` placed in `.claude` and other host directories, and if needed remove the project's `.workflow` directory with Spec and Knowhow.
FAQ
How do I install Maestro-Flow for Claude Code?
Run `npm install -g maestro-flow@0.5.82`, then `maestro install` and choose components. Node.js 22.19 or newer and Claude Code are required. Afterwards commands such as `/maestro` and `/maestro-ralph` are available in Claude Code.
What does `/maestro-ralph` do?
It takes a goal in plain language, detects the project stage and builds a chain of analyze, plan, execute, verify, review and test commands. After a failure it inserts debug, fix and retry itself, and for a new project it starts with brainstorm and blueprint. `/maestro-ralph -c` resumes paused work.
Which agents work together?
One flow can mix Claude, Codex, Gemini, Qwen, OpenCode and Grok. Claude Code or Grok Build is the host, and the others attach through `delegate`. Codex CLI and agy CLI are installed separately.
What is Odyssey mode?
Long autonomous loops that adjust at every checkpoint: `/maestro-odyssey <task> --mode debug` and six more modes, among them planex, improve, review, security, defensive and ui. A loop runs until the acceptance criteria are met. The security and defensive modes only read code.
How do I see progress?
With `maestro session status`. A session opens with `maestro session open`, `maestro run next` starts the next step, `maestro run complete --advance` records a finished step and `maestro session complete` closes everything.
Discussion
No questions or reviews yet.
Related
CLI toolsA skill with 25 commands to audit and improve the prompts, tools and agent designs of a project in Cursor, Claude Code and Codex
An orchestration plugin for Claude Code, Codex, Gemini CLI and Qwen Code: 39 specialists, parallel subagents, persistent sessions and standalone audits
maestro keeps work, decisions, sessions and evidence of humans and agents in the shared Git root, locally, with no service
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
A process kit for agents: a skill router, project memory in a DEV folder and result verification before saying done.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Maestro-Flow (this card) | no | 575 | |
| OpenSpec | no | 74,686 | takes development from proposal and requirements to tasks, while Maestro-Flow picks the chain from the goal and brings in several agents |
| Ruflo | no | 81,490 | a plugin marketplace and agent swarms for Claude Code, while Maestro-Flow builds a staged chain with decision points |
README in short
The README summarizes four capabilities: adaptive orchestration, mixed agents, accumulating knowledge and long loops. Then come installation, the Ralph, `/maestro` and `/maestro-next` entry points, Odyssey modes, exact search and an index of guides on installation, commands, hooks and MCP.