--- title: "Auto mode" description: "SF's autonomous execution engine — run /sf auto, walk away, come back to built software with clean git history." --- Auto mode is a **state machine driven by files on disk**. It reads `.sf/STATE.md`, determines the next unit of work, creates a fresh agent session with pre-loaded context, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit. ## The loop ``` Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice ↓ (all slices done) Validate → Complete Milestone ``` - **Plan** — scouts the codebase, researches docs, decomposes the slice into tasks - **Execute** — runs each task in a fresh context window - **Complete** — writes summary, UAT script, marks roadmap, commits - **Reassess** — checks if the roadmap still makes sense - **Validate** — reconciliation gate after all slices; catches gaps before sealing the milestone ## Key properties ### Fresh session per unit Every task, research phase, and planning step gets a clean context window. The dispatch prompt includes everything needed — task plans, prior summaries, dependency context, decisions register — so the LLM starts oriented. ### Context pre-loading | Inlined artifact | Purpose | |------------------|---------| | Task plan | What to build | | Slice plan | Where this task fits | | Prior task summaries | What's already done | | Dependency summaries | Cross-slice context | | Roadmap excerpt | Overall direction | | Decisions register | Architectural context | The amount of context inlined is controlled by your [token profile](/guides/token-optimization). Budget mode inlines minimal context; quality mode inlines everything. ### Git isolation SF isolates milestone work using one of three modes (configured via `git.isolation` in preferences): - **`none`** (default) — work happens on your current branch. No isolation overhead. - **`worktree`** — each milestone runs in its own git worktree. Squash-merged to main on completion. - **`branch`** — work happens on a `milestone/` branch in the project root. Useful for submodule-heavy repos. See [git strategy](/guides/git-strategy) for details. ### Crash recovery A lock file tracks the current unit. If the session dies, the next `/sf auto` synthesizes a recovery briefing from tool calls that made it to disk and resumes with full context. **Headless auto-restart:** When running `sf headless auto`, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Combined with crash recovery, this enables overnight "run until done" execution. ### Provider error recovery | Error type | Examples | Action | |-----------|----------|--------| | Rate limit | 429, "too many requests" | Auto-resume after retry-after header or 60s | | Server error | 500, 502, 503, "overloaded" | Auto-resume after 30s | | Permanent | "unauthorized", "invalid key" | Pause indefinitely (requires manual resume) | ### Stuck detection A sliding-window analysis detects stuck loops — catching cycles like A→B→A→B as well as single-unit repeats. On detection, SF retries once with a diagnostic prompt. If it fails again, auto mode stops with the exact file it expected. ### Timeout supervision | Timeout | Default | Behavior | |---------|---------|----------| | Soft | 20 min | Warns the LLM to wrap up | | Idle | 10 min | Detects stalls, intervenes | | Hard | 30 min | Pauses auto mode | Configure in preferences: ```yaml auto_supervisor: soft_timeout_minutes: 20 idle_timeout_minutes: 10 hard_timeout_minutes: 30 ``` ### Incremental memory SF maintains a `KNOWLEDGE.md` file — an append-only register of project-specific rules, patterns, and lessons learned. The agent reads it at the start of every unit and appends when discovering recurring issues or non-obvious patterns. ### Verification enforcement ```yaml verification_commands: - npm run lint - npm run test verification_auto_fix: true verification_max_retries: 2 ``` Failures trigger auto-fix retries — the agent sees the output and attempts to fix issues before advancing. ### HTML reports After milestone completion, SF auto-generates a self-contained HTML report with progress tree, dependency graph, cost/token metrics, execution timeline, and changelog. ```yaml auto_report: true # enabled by default ``` Generate manually with `/sf export --html`, or for all milestones with `/sf export --html --all`. ### Reactive task execution When `reactive_execution: true` is set, SF derives a dependency graph from IO annotations in task plans. Tasks that don't conflict are dispatched in parallel via subagents. ```yaml reactive_execution: true # disabled by default ``` ## Controlling auto mode ``` /sf auto ``` Press **Escape**. The conversation is preserved. You can interact with the agent, inspect state, or resume. ``` /sf auto ``` Auto mode reads disk state and picks up where it left off. ``` /sf stop ``` Stops auto mode gracefully. Can be run from a different terminal. ### Steer during execution ``` /sf steer ``` Hard-steer plan documents without stopping the pipeline. Changes are picked up at the next phase boundary. ### Capture thoughts ``` /sf capture "add rate limiting to API endpoints" ``` Fire-and-forget thought capture. Triaged automatically between tasks. See [captures and triage](/guides/captures-triage). ## Dashboard `Ctrl+Alt+G` or `/sf status` shows real-time progress: - Current milestone, slice, and task - Auto mode elapsed time and phase - Per-unit cost and token breakdown - Cost projections - Pending capture count ## Phase skipping Token profiles can skip phases to reduce cost: | Phase | `budget` | `balanced` | `quality` | |-------|----------|------------|-----------| | Milestone research | Skipped | Runs | Runs | | Slice research | Skipped | Skipped | Runs | | Reassess roadmap | Skipped | Runs | Runs | See [token optimization](/guides/token-optimization) for details.