Auto Run & Playbooks

Fresh

Auto Run is Maestro's core automation engine. It processes markdown checklists through AI agents, spawning a fresh session for each task.

How Auto Run Works

Setup

1. Open the Auto Run tab (Ctrl+Shift+1)
2. Select a folder containing .md files
3. Each .md file becomes a selectable document

Task Format

# Feature Implementation Plan

- [ ] Implement user authentication module
- [ ] Add unit tests for the login flow
- [ ] Update API documentation with new endpoints
- [ ] Add input validation to signup form

Press Ctrl+L to insert a checkbox at the cursor position.

Session Isolation

Each task gets a completely fresh AI session with its own unique session ID. No conversation history bleeds between tasks. This is critical for consistent results in loop mode.

Run Options

Option	Description
Single document	Select one .md file and click Run
Multiple documents	Click Run → "+ Add Docs" → drag to reorder
Reset on Completion	Creates a working copy in Runs/ subfolder; original stays untouched
Duplicate	Run the same document multiple times
Loop Mode	Cycles back to first document after last is complete
Dispatch to Worktree	Runs the entire Auto Run in an isolated git branch

Expanded Editor

Press Ctrl+Shift+E for fullscreen editing with:

• Edit/preview toggle
• Document selector
• Run controls

Progress Tracking

• Tasks processed top to bottom
• Documents skipped if no unchecked tasks remain
• Completed tasks marked with [x]
• Each completion logged to History panel with:
  • AUTO label
  • Session ID (clickable — jumps to that session)
  • Summary
  • Duration
  • Cost

Parallel Execution

Auto Run can run across multiple agents without conflict — each works in its own directory.

For same-repository parallel work, use Git Worktrees to isolate branches.

Environment Variable

MAESTRO_SESSION_RESUMED=1 is set when resuming a session (not set for new sessions). Use in hooks to skip new-session-only logic.

---

Playbooks

Playbooks are saved Auto Run configurations for repeatable workflows.

Save a Playbook

Configure your documents + order + options → click "Save as Playbook" → name it.

Load a Playbook

"Load Playbook" dropdown → select → optionally update or discard changes.

Playbook Exchange

Community-contributed playbooks accessible via Ctrl+K → "Playbook Exchange" or the Exchange button in Auto Run panel.

• Browse by category (Development, Security, DevOps, etc.)
• Search by title, description, tags
• Preview documents before importing
• One-click import to your Auto Run folder
• Cached for 6 hours; force refresh available
• Contribute at the Maestro-Playbooks repository

Local Manifest (Private Playbooks)

Create <userData>/local-manifest.json for custom/private playbooks:

{
  "playbooks": [
    {
      "id": "my-custom-workflow",
      "title": "My Custom Workflow",
      "description": "Internal team workflow",
      "category": "Development",
      "documents": ["setup.md", "implement.md", "test.md"]
    }
  ]
}

• Hot-reloads on save (500ms debounce)
• Appears in Exchange with a blue "Local" badge
• Use same id as an official playbook to override it locally

See Also

• Inline Wizard — Auto-generate playbook documents
• Git Worktrees — Isolate Auto Run to a branch
• Auto Run Workflow — End-to-end workflow guide
• History — Review Auto Run results