Auto mode is GSD's autonomous execution engine. Run /gsd 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 .gsd/STATE.md, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
Each slice flows through phases automatically:
Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
↓ (all slices done)
Validate Milestone → Complete Milestone
- Plan — scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves
- 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 Milestone — reconciliation gate after all slices complete; compares roadmap success criteria against actual results, catches gaps before sealing the milestone
Every task, research phase, and planning step gets a clean context window. No accumulated garbage. No degraded quality from context bloat. The dispatch prompt includes everything needed — task plans, prior summaries, dependency context, decisions register — so the LLM starts oriented instead of spending tool calls reading files.
The dispatch prompt is carefully constructed with:
| 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. Budget mode inlines minimal context; quality mode inlines everything.
GSD isolates milestone work using one of three modes (configured via git.isolation in preferences):
worktree(default): Each milestone runs in its own git worktree at.gsd/worktrees/<MID>/on amilestone/<MID>branch. All slice work commits sequentially — no branch switching, no merge conflicts mid-milestone. When the milestone completes, it's squash-merged to main as one clean commit.branch: Work happens in the project root on amilestone/<MID>branch. Useful for submodule-heavy repos where worktrees don't work well.none: Work happens directly on your current branch. No worktree, no milestone branch. Ideal for hot-reload workflows where file isolation breaks dev tooling.
See Git Strategy for details.
When your project has independent milestones, you can run them simultaneously. Each milestone gets its own worker process and worktree. See Parallel Orchestration for setup and usage.
A lock file tracks the current unit. If the session dies, the next /gsd auto reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
Headless auto-restart (v2.26): When running gsd headless auto, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). Configure with --max-restarts N. SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight "run until done" execution.
GSD classifies provider errors and auto-resumes when safe:
| Error type | Examples | Action |
|---|---|---|
| Rate limit | 429, "too many requests" | Auto-resume after retry-after header or 60s |
| Server error | 500, 502, 503, "overloaded", "api_error" | Auto-resume after 30s |
| Permanent | "unauthorized", "invalid key", "billing" | Pause indefinitely (requires manual resume) |
No manual intervention needed for transient errors — the session pauses briefly and continues automatically.
GSD 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 to it when discovering recurring issues, non-obvious patterns, or rules that future sessions should follow. This gives auto-mode cross-session memory that survives context window boundaries.
When context usage reaches 70%, GSD sends a wrap-up signal to the agent, nudging it to finish durable output (commit, write summaries) before the context window fills. This prevents sessions from hitting the hard context limit mid-task with no artifacts written.
Commits are generated from task summaries — not generic "complete task" messages. Each commit message reflects what was actually built, giving clean git log output that reads like a changelog.
If the same unit dispatches twice (the LLM didn't produce the expected artifact), GSD retries once with a deep diagnostic prompt. If it fails again, auto mode stops with the exact file it expected, so you can intervene.
When auto mode fails or produces unexpected results, /gsd forensics provides structured post-mortem analysis. It inspects activity logs, crash locks, and session state to identify root causes — whether the failure was a model error, missing context, a stuck loop, or a broken tool call. See Troubleshooting for more on diagnosing issues.
Three timeout tiers prevent runaway sessions:
| Timeout | Default | Behavior |
|---|---|---|
| Soft | 20 min | Warns the LLM to wrap up |
| Idle | 10 min | Detects stalls, intervenes |
| Hard | 30 min | Pauses auto mode |
Recovery steering nudges the LLM to finish durable output before timing out. Configure in preferences:
auto_supervisor:
soft_timeout_minutes: 20
idle_timeout_minutes: 10
hard_timeout_minutes: 30Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
See Cost Management.
After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing. This can be skipped with the balanced or budget token profiles.
Configure shell commands that run automatically after every task execution:
verification_commands:
- npm run lint
- npm run test
verification_auto_fix: true # auto-retry on failure (default)
verification_max_retries: 2 # max retry attempts (default: 2)Failures trigger auto-fix retries — the agent sees the verification output and attempts to fix the issues before advancing. This ensures code quality gates are enforced mechanically, not by LLM compliance.
For projects where you want human review before each slice begins:
require_slice_discussion: trueAuto-mode pauses before each slice, presenting the slice context for discussion. After you confirm, execution continues. Useful for high-stakes projects where you want to review the plan before the agent builds.
After a milestone completes, GSD auto-generates a self-contained HTML report in .gsd/reports/. Reports include project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base. No external dependencies — all CSS and JS are inlined.
auto_report: true # enabled by defaultGenerate manually anytime with /gsd export --html, or generate reports for all milestones at once with /gsd export --html --all (v2.28).
v2.28 hardens auto-mode reliability with multiple safeguards: atomic file writes prevent corruption on crash, OAuth fetch timeouts (30s) prevent indefinite hangs, RPC subprocess exit is detected and reported, and blob garbage collection prevents unbounded disk growth. Combined with the existing crash recovery and headless auto-restart, auto-mode is designed for true "fire and forget" overnight execution.
/gsd auto
Press Escape. The conversation is preserved. You can interact with the agent, inspect state, or resume.
/gsd auto
Auto mode reads disk state and picks up where it left off.
/gsd stop
Stops auto mode gracefully. Can be run from a different terminal.
/gsd steer
Hard-steer plan documents during execution without stopping the pipeline. Changes are picked up at the next phase boundary.
/gsd capture "add rate limiting to API endpoints"
Fire-and-forget thought capture. Captures are triaged automatically between tasks. See Captures & Triage.
/gsd visualize
Open the workflow visualizer — interactive tabs for progress, dependencies, metrics, and timeline. See Workflow Visualizer.
Ctrl+Alt+G or /gsd status shows real-time progress:
- Current milestone, slice, and task
- Auto mode elapsed time and phase
- Per-unit cost and token breakdown
- Cost projections
- Completed and in-progress units
- Pending capture count (when captures are awaiting triage)
- Parallel worker status (when running parallel milestones — includes 80% budget alert)
Token profiles can skip certain 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 for details.
When enabled, auto-mode automatically selects cheaper models for simple units (slice completion, UAT) and reserves expensive models for complex work (replanning, architectural tasks). See Dynamic Model Routing.