Maestro/docs/autorun-playbooks.md

title

title
Auto Run + Playbooks

Auto Run is a file-system-based document runner that lets you batch-process tasks using AI agents. Select a folder containing markdown documents with task checkboxes, and Maestro will work through them one by one, spawning a fresh AI session for each task.

Setting Up Auto Run

1. Navigate to the Auto Run tab in the right panel (Cmd+Shift+1)
2. Select a folder containing your markdown task documents
3. Each .md file becomes a selectable document

Creating Tasks

Use markdown checkboxes in your documents:

# Feature Implementation Plan

- [ ] Implement user authentication
- [ ] Add unit tests for the login flow
- [ ] Update API documentation

Tip: Press Cmd+L (Mac) or Ctrl+L (Windows/Linux) to quickly insert a new checkbox at your cursor position.

Running Single Documents

1. Select a document from the dropdown
2. Click the Run button (or the ▶ icon)
3. Customize the agent prompt if needed, then click Go

Multi-Document Batch Runs

Auto Run supports running multiple documents in sequence:

1. Click Run to open the Batch Runner Modal
2. Click + Add Docs to add more documents to the queue
3. Drag to reorder documents as needed
4. Configure options per document:
   • Reset on Completion - Creates a working copy in Runs/ subfolder instead of modifying the original. The original document is never touched, and working copies (e.g., TASK-1735192800000-loop-1.md) serve as audit logs.
   • Duplicate - Add the same document multiple times
5. Enable Loop Mode to cycle back to the first document after completing the last
6. Click Go to start the batch run

Playbooks

Save your batch configurations for reuse:

1. Configure your documents, order, and options
2. Click Save as Playbook and enter a name
3. Load saved playbooks from the Load Playbook dropdown
4. Update or discard changes to loaded playbooks

Progress Tracking

The runner will:

• Process tasks serially from top to bottom
• Skip documents with no unchecked tasks
• Show progress: "Document X of Y" and "Task X of Y"
• Mark tasks as complete (- [x]) when done
• Log each completion to the History panel

Session Isolation

Each task executes in a completely fresh AI session with its own unique session ID. This provides:

• Clean context - No conversation history bleeding between tasks
• Predictable behavior - Tasks in looping playbooks execute identically each iteration
• Independent execution - The agent approaches each task without memory of previous work

This isolation is critical for playbooks with Reset on Completion documents that loop indefinitely. Each loop creates a fresh working copy from the original document, and the AI approaches it without memory of previous iterations.

Environment Variables

Maestro sets environment variables that your agent hooks can use to customize behavior:

Variable	Value	Description
MAESTRO_SESSION_RESUMED	1	Set when resuming an existing session (not set for new sessions)

Example: Conditional Hook Execution

Since Maestro spawns a new agent process for each message (batch mode), agent "session start" hooks will run on every turn. Use MAESTRO_SESSION_RESUMED to skip hooks on resumed sessions:

# In your agent's session start hook
[ "$MAESTRO_SESSION_RESUMED" = "1" ] && exit 0
# ... rest of your hook logic for new sessions only

This works with any agent provider (Claude Code, Codex, OpenCode) since the environment variable is set by Maestro before spawning the agent process.

History & Tracking

Each completed task is logged to the History panel with:

• AUTO label indicating automated execution
• Session ID pill (clickable to jump to that AI conversation)
• Summary of what the agent accomplished
• Full response viewable by clicking the entry

Keyboard navigation in History:

• Up/Down Arrow - Navigate entries
• Enter - View full response
• Esc - Close detail view and return to list

Auto-Save

Documents auto-save after 5 seconds of inactivity, and immediately when switching documents. Full undo/redo support with Cmd+Z / Cmd+Shift+Z.

Image Support

Paste images directly into your documents. Images are saved to an images/ subfolder with relative paths for portability.

Stopping the Runner

Click the Stop button at any time. The runner will:

• Complete the current task before stopping
• Preserve all completed work
• Allow you to resume later by clicking Run again

Parallel Auto Runs

Auto Run can execute in parallel across different agents without conflicts — each agent works in its own project directory, so there's no risk of clobbering each other's work.

Same project, parallel work: To run multiple Auto Runs in the same repository simultaneously, create worktree sub-agents from the git branch menu (see Git Worktrees). Each worktree operates in an isolated directory with its own branch, enabling true parallel task execution on the same codebase.