MaestrunStar2

~/your-project $ maestrun start

Conduct your coding agents.

Maestrun turns your requirements into a plan you review, then runs every task through Planning → Implementation → Tests with Codex, Claude Code, GitHub Copilot CLI, or Grok Build. Pick the executor, model and effort for each stage. Ready to use in a few minutes.

npm install --global @maestrun/maestrun@beta

Beta · Node.js 24 LTS · Linux, macOS, WSL

Maestrun · task command center

All 3Working 2Done 0Waiting 1Issues 0

~/demo/.maestrun/samples/run-01XNLZ

0/3 tasks · 3/12 steps · 25% · 0:58

TaskNamein/outStatusStageModelEffortSteps
Add two numbers independently170K/1228WorkingIntegrationgpt-6.1-sol–3/4
Clamp a value and demonstrate one QA repair102K/852WorkingImplementationgpt-6.1-solmedium0/4
Use both integrated resultsn/aWaiting–gpt-6.1-sol–0/4

[ Flow ] PgUp/PgDn
sample-clamp · Clamp a value and demonstrate one QA repair

  1. ImplementationIn progressgpt-6.1-sol · mediumin: 51005 · out: 556
  2. TestsWaitinggpt-6.1-sol · lowin: n/a · out: n/a
  3. QARefactor · needs changesgpt-6.1-sol · highin: 50674 · out: 296
  4. IntegrationWaitingGit · localno model calls

Implementation · codex / gpt-6.1-sol · Effort: medium

Automatic repair (1/5) after qa: Changes needed: clamp.mjs:2 ignores max, so clamp(15,0,10) returns 15 instead of 10

PgUp/PgDn steps · ↑/↓ tasks · Tab filter · F flow · I instructions · Enter details · Ctrl+C options

Replay of maestrun sample advanced with codex / gpt-6.1-sol, built from real captures. Effort levels per stage show the setting; token counts are illustrative. Click a task to follow its flow.

Why Maestrun hits the mark.

  1. 1

    Quick to set up

    Install from npm, run maestrun start, pick an executor and model. Environment checks catch setup problems before planning.

  2. 2

    Easy to run

    Review the plan, start the run, and follow every task live in the terminal, in the foreground or background.

  3. 3

    Highly customizable

    Stages, executor, model and effort per stage, Markdown steps and terminal layout, all in readable JSON.

  4. 4

    Any agent, any stage

    Codex, Claude Code, GitHub Copilot CLI or Grok Build, used alone or mixed across stages.

12345678
  1. 5

    Repairs itself

    A failed check sends the task back to Implementation, up to 5 times per task by default.

  2. 6

    Resumes where it stopped

    Completed stages are checkpointed in run.json. Detach with Ctrl+C and reconnect any time.

  3. 7

    Runs in parallel

    Each task gets its own Git worktree and is merged back into your project when its stages pass.

  4. 8

    Reusable everywhere

    Save a workflow as a template and import it in another project or on another machine.

Every stage. Its own model.

Let Planning think hard while Tests stay quick. Each stage gets its own executor, exact model and effort level, or you use one for the whole workflow. Edit the stages below; the config.json Maestrun reads updates as you go. Add as many steps as you need: QA, Review, or your own written in Markdown.

StageExecutorModelEffort
Planning
Implementation
Tests

Add as many steps as you need 3 stages

Your own steps run from Markdown instructions in .maestrun/steps/. Model IDs here are placeholders: enter an exact ID your account can use. Effort lists show what each executor accepts.

.maestrun/config.json
{
  "version": 1,
  "stages": [
    {
      "id": "planning",
      "executor": "claude",
      "model": "your-claude-model",
      "effort": "high"
    },
    {
      "id": "implementation",
      "executor": "codex",
      "model": "your-codex-model",
      "effort": "medium"
    },
    {
      "id": "testing",
      "executor": "copilot",
      "model": "your-copilot-model"
    }
  ],
  "execution": {
    "mode": "sequential"
  }
}

Same thing from the terminal: maestrun config stages planning effort high

Simple to start.

  1. Install the CLI.

    npm install --global @maestrun/maestrun@beta

  2. Open your project and start.

    cd your-project && maestrun start

  3. Maestrun checks your environment, then asks for an executor, an exact model, and Standard or Customize.

  4. Describe your requirements, review the task preview, and start the run.

Standard uses the same executor and model for Planning → Implementation → Tests, in sequence. Existing configuration, plans and progress are reused when you run maestrun start again.

Highly customizable.

  • .maestrun/per project
  • config.jsonstages; executor, model and effort per stage; sequential or parallel; concurrency 1–16; repairs 0–100; timeout
  • steps/*.mdyour own workflow steps in Markdown, as many as you need
  • layout.jsonterminal columns and flowchart position
  • run.jsoncheckpoints that make runs resumable
  • ~/.maestrun/for every project
  • config.jsonglobal defaults and step presets
  • templates/saved workflows to reuse, export and import

terminal

maestrun init --advanced                     # full workflow editor
maestrun config stages planning effort high  # tune one stage
maestrun config execution.maxRepairs 3       # change the repair limit
maestrun template save my-workflow           # reuse it anywhere
maestrun template export team.json           # hand it to your team
All advanced settings →

Plan first. Then run.

The plan is a Markdown task list you can read and edit before anything executes. Each task then walks through its stages; when a model reports a failure, Maestrun restarts at Implementation, up to five times by default. Completed work is checkpointed, so a stopped run picks up where it left off.

One run, start to finishYour requirements go into maestrun start, which checks the environment and lets you pick an executor and model. Maestrun writes a plan you review, then fans out tasks, in parallel Git worktrees when enabled. Every task runs Implementation, Tests, optional QA and Integration. A failed check loops back to Implementation up to five times. Progress is saved in run.json so you can resume.one run, start to finishyour requirements$ maestrun startchecking environment…checks your setup, then you pickcodex · claude · copilot · grok+ an exact modelplan.mdtask apitask uitask docsyoureviewfirsttask apitask uitask docsparallel? one Gitworktree per taskthen, for every taskImplementationany executor, any modelTestsQAoptional stepIntegrationGit · local mergefailed check? automatic repair, up to 5× per taskrun.jsonsaved · resume anytime

This is the actual terminal.

A real capture of maestrun sample advanced: QA asked for changes, so the clamp task went back to Implementation for automatic repair 1 of 5. The flowchart shows the loop as it happens.

Enter
Open task details
F
Toggle the stage flowchart
I
Send instructions to a running model task
Tab
Filter by status
Ctrl+C
Move the run to the background, or cancel

Try it: maestrun sample · maestrun sample advanced

Maestrun's task command center during the advanced sample. The clamp task is selected; its flowchart shows QA marked Refactor · needs changes with an arrow looping back to Implementation, and the footer reads Automatic repair (1/5) after qa.

Bring your own agents.

Maestrun doesn't replace your coding agent; it conducts it. Install and sign in to at least one executor. Planning, execution, and samples run on your executor account.

Everything Maestrun conductsexecutors: Codex, Claude Code, GitHub Copilot CLI, Grok Build. commands: start, run --background, doctor, sample advanced, template save, config. each stage: its own executor, an exact model ID, an effort level, custom steps (.md). plain files: .maestrun/config.json, .maestrun/steps/*.md, .maestrun/run.json, ~/.maestrun/templates/CodexClaude CodeGitHub Copilot CLIGrok Buildstartrun --backgrounddoctorsample advancedtemplate saveconfigits own executoran exact model IDan effort levelcustom steps (.md).maestrun/config.json.maestrun/steps/*.md.maestrun/run.json~/.maestrun/templates/executorscommandseach stageplain filesmaestrunone conductor, your agents
ExecutorInstallSign in
Codex
npm install -g @openai/codex
codex login
Claude CodeInstallation guide
claude auth login
GitHub Copilot CLI
npm install -g @github/copilot
copilot login
Grok Build
npm install -g @xai-official/grok
grok login

Stop anytime. Resume.

Field notesCtrl+C: choose background or cancel. maestrun reconnects later; run --status prints the report. parallel mode: one Git worktree per task, three-way merge back into your project. Git 2.38+. repair cycles: 5 per task per run by default. execution.maxRepairs: 0–100; 0 turns repairs off. press I: send instructions to a running model task. Codex steers; others queue them. maestrun doctor: checks install, auth, files and locks. Makes no model calls; never deletes locks. templates: save a workflow, export it, import it on another machine, then init --template.Ctrl+Cchoose background or cancel.maestrun reconnects later;run --status prints the report.parallel modeone Git worktree per task,three-way merge back intoyour project. Git 2.38+.repair cycles5 per task per run by default.execution.maxRepairs: 0–100;0 turns repairs off.press Isend instructions to arunning model task. Codexsteers; others queue them.maestrun doctorchecks install, auth, filesand locks. Makes no modelcalls; never deletes locks.templatessave a workflow, export it,import it on another machine,then init --template.field notes from the advanced guide
CommandWhat it does
maestrun doctorCheck installation, authentication, files, and locks
maestrun run --dry-runPreview tasks without model calls
maestrun runRun or resume unfinished tasks
maestrun run --backgroundStart execution in the background
maestrunReconnect to a background session
maestrun run --statusRead the saved report

What's new.

Full changelog · RSS

  1. 0.1.1-beta.2betaNEWESTMaestrun 0.1.1-beta.2 adds documentation screenshots from real simple and advanced sample runs, including the automatic QA → Implementation repair flow.
  2. 0.1.1-beta.1betaARRIVEDSuperseded by 0.1.1-beta.2. This release was not published to npm because its CI integration test exceeded the previous timeout. Use npm install --global @maestrun/maestrun@beta.
  3. 0.1.1-beta.0betaARRIVEDMaestrun 0.1.1-beta.0 is available on npm under the beta tag. This is a Beta release; bugs may occur, and contributions through issues and pull requests are welcome.
  4. 0.1.0latestSTABLEFirst release of the Maestrun CLI, licensed under SUL-1.0.

Two commands to your first run.

npm install --global @maestrun/maestrun@beta
cd your-project && maestrun start

Maestrun is in Beta (v0.1.1-beta.2). Bugs may occur; issues and pull requests are welcome. If it helps you ship, star it on GitHub so more people find it.