Local state

The default database is .maestro/maestro.db. It stores projects, tasks, Goal runs and steps, events, Chat threads/messages, provider policy, reviews, Feature Plans, Work Graphs and usage data. SQLite is the source of truth for the local control plane.

Filesystem boundaries

• .env.local / .env: local configuration and secrets; never commit.
• .maestro/: database, runtime metadata and artifacts; ignore in Git.
• Execution/worktrees root: task branches and isolated working directories, normally outside the checkout (for example C:\MaestroRuntime\...).
• Packaged app data: %APPDATA%\Maestro for config/database/runtime state.

The runtime stores bounded evidence and redacts sensitive text before exposing it through the UI or notifications. A task’s worktree and checkpoint are preserved when a Goal waits or blocks so recovery does not require inventing a new task.

Backups and reset

Stop Maestro before copying the database. Keep the database and worktrees together when preserving an in-flight task. To start clean, stop the runtime and move the user data directory aside; do not delete it blindly while a process is running.