Overview Auto Run enables automated processing of Markdown documents with task lists. Playbooks save your batch configurations for repeated execution via the UI or CLI.
Auto Run watches a folder of Markdown files and processes open tasks (- [ ]) when you click Run or execute a playbook.
Auto Run Basics Folder Setup Auto Run requires a folder containing Markdown documents:
Select Folder
Click “Select Folder” in the Auto Run panel to choose your documents directory
Create Documents
Add .md files with task lists: # My Tasks - [ ] First task to complete - [ ] Second task - [ x ] Already completed task
Run
Click Run to process unchecked tasks
Auto Run recognizes standard Markdown checkboxes:
# Task Categories ## Open Tasks (will be processed) - [ ] Unchecked task - [ ] Another open task ## Completed Tasks (skipped) - [ x ] Checked task - [ X ] Also checked (uppercase X)
Template Variables Use template variables in your documents for dynamic content:
Project: {{PROJECT_NAME}} Date: {{CURRENT_DATE}} Branch: {{GIT_BRANCH}}
Playbooks Playbooks save batch configurations for repeated execution:
Creating a Playbook
Configure Batch Run
In the Batch Runner modal, select:
Documents to process
Loop settings (optional)
Worktree configuration (optional)
Save as Playbook
Click “Save as Playbook” and provide:
Name
Description (optional)
Execute Anytime
Run from UI or CLI with saved configuration
Playbook Structure interface Playbook { id : string name : string description ?: string documents : string [] // Document filenames loopEnabled : boolean // Run until no open tasks maxLoops : number | null // Limit iterations (null = unlimited) sessionId : string // Agent that owns this playbook createdAt : number updatedAt : number }
Loop Mode Enable loop mode to run until all tasks are completed:
Single Pass
Loop Until Complete
Limited Loops
Processes each document once loopEnabled : true maxLoops : null // Unlimited
Runs until no open tasks remain loopEnabled : true maxLoops : 5 // Maximum 5 iterations
Runs up to 5 times or until complete CLI Execution Run playbooks from the command line for automation:
List Playbooks # List all playbooks maestro-cli list playbooks # List playbooks for specific agent maestro-cli list playbooks --agent < agent-i d > # JSON output for scripting maestro-cli list playbooks --json
Run Playbook # Run a playbook (supports partial IDs) maestro-cli playbook < playbook-i d > # Dry run to preview maestro-cli playbook < playbook-i d > --dry-run # Wait if agent is busy maestro-cli playbook < playbook-i d > --wait # JSON output for parsing maestro-cli playbook < playbook-i d > --json # Debug mode maestro-cli playbook < playbook-i d > --debug --verbose
Playbook IDs support prefix matching. You can use just the first few characters if unambiguous.
Human Readable
JSON Output
maestro-cli playbook abc123 Running playbook: Update Documentation Agent: My Agent Documents: 5 Loop: enabled (max 3 ) [1/5] Processing Document1.md... ✓ Task completed: Update introduction ✓ Task completed: Add examples
Batch Processing Events The batch processor emits events during execution:
type RunEvent = | { type : 'start' ; playbook : string ; documents : number } | { type : 'document_start' ; index : number ; name : string } | { type : 'document_complete' ; index : number ; duration : number } | { type : 'task_complete' ; task : string } | { type : 'loop_start' ; iteration : number } | { type : 'loop_complete' ; totalIterations : number } | { type : 'complete' ; totalDuration : number } | { type : 'error' ; message : string }
Agent Concurrency Playbooks prevent concurrent execution on the same agent:
If an agent is already running a playbook (from CLI or desktop), new executions will fail unless --wait is used.
# Will fail if agent is busy maestro-cli playbook abc123 # Will wait for agent to become available maestro-cli playbook abc123 --wait
Marketplace Integration Import playbooks from the marketplace:
Browse Marketplace
Open Marketplace modal (Cmd+Shift+M)
Find Playbook
Search for playbooks by name or description
Import
Click Import to add to your agent
Customize
Edit documents and settings as needed
Export & Share Export playbooks as ZIP files with all assets:
// Exported structure playbook . zip ├── playbook . json // Playbook configuration ├── documents / │ ├── Document1 . md // All referenced documents │ └── Document2 . md └── images / // Embedded images from documents └── screenshot . png
Exported playbooks include all documents and embedded images, making them portable across machines.
Error Handling Batch runs can pause on errors:
// When a document fails batchRunState . errorPaused = true batchRunState . error = "Agent error message" batchRunState . errorDocumentIndex = 2 // Recovery options - Skip current document - Abort batch run - Resume ( if error resolved )