Architecture Overview
March 17, 2026 · View on GitHub
GSD is a TypeScript application built on the Pi SDK. It embeds the Pi coding agent and extends it with the GSD workflow engine, auto mode state machine, and project management primitives.
System Structure
gsd (CLI binary)
└─ loader.ts Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
└─ cli.ts Wires SDK managers, loads extensions, starts InteractiveMode
├─ onboarding.ts First-run setup wizard (LLM provider + tool keys)
├─ wizard.ts Env hydration from stored auth.json credentials
├─ app-paths.ts ~/.gsd/agent/, ~/.gsd/sessions/, auth.json
├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/
└─ src/resources/
├─ extensions/gsd/ Core GSD extension
├─ extensions/... 12 supporting extensions
├─ agents/ scout, researcher, worker
├─ AGENTS.md Agent routing instructions
└─ GSD-WORKFLOW.md Manual bootstrap protocol
gsd headless Headless mode — CI/cron orchestration via RPC child process
gsd --mode mcp MCP server mode — exposes tools over stdin/stdout
vscode-extension/ VS Code extension — chat participant (@gsd), sidebar dashboard, RPC integration
Key Design Decisions
State Lives on Disk
.gsd/ is the sole source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions. This enables crash recovery, multi-terminal steering, and session resumption.
Two-File Loader Pattern
loader.ts sets all environment variables with zero SDK imports, then dynamically imports cli.ts which does static SDK imports. This ensures PI_PACKAGE_DIR is set before any SDK code evaluates.
pkg/ Shim Directory
PI_PACKAGE_DIR points to pkg/ (not project root) to avoid Pi's theme resolution colliding with GSD's src/ directory. Contains only piConfig and theme assets.
Always-Overwrite Sync
Bundled extensions and agents are synced to ~/.gsd/agent/ on every launch, not just first run. This means npm update -g takes effect immediately.
Lazy Provider Loading
LLM provider SDKs (Anthropic, OpenAI, Google, etc.) are lazy-loaded on first use rather than imported at startup. This significantly reduces cold-start time — only the provider you actually connect to gets loaded.
Fresh Session Per Unit
Every dispatch creates a new agent session. The LLM starts with a clean context window containing only the pre-inlined artifacts it needs. This prevents quality degradation from context accumulation.
Bundled Extensions
| Extension | What It Provides |
|---|---|
| GSD | Core workflow engine — auto mode, state machine, commands, dashboard |
| Browser Tools | Playwright-based browser automation — navigation, forms, screenshots, PDF export, device emulation, visual regression, structured data extraction, route mocking, accessibility tree inspection, and semantic actions |
| Search the Web | Brave Search, Tavily, or Jina page extraction |
| Google Search | Gemini-powered web search with AI-synthesized answers |
| Context7 | Up-to-date library/framework documentation |
| Background Shell | Long-running process management with readiness detection |
| Subagent | Delegated tasks with isolated context windows |
| Mac Tools | macOS native app automation via Accessibility APIs |
| MCPorter | Lazy on-demand MCP server integration |
| Voice | Real-time speech-to-text (macOS, Linux) |
| Slash Commands | Custom command creation |
| LSP | Language Server Protocol — diagnostics, definitions, references, hover, rename |
| Ask User Questions | Structured user input with single/multi-select |
| Secure Env Collect | Masked secret collection |
| Async Jobs | Background command execution with async_bash, await_job, cancel_job |
| Remote Questions | Discord, Slack, and Telegram integration for headless question routing |
| TTSR | Tool-triggered system rules — conditional context injection based on tool usage |
| Universal Config | Discovery of existing AI tool configurations (Claude Code, Cursor, Windsurf, etc.) |
Bundled Agents
| Agent | Role |
|---|---|
| Scout | Fast codebase recon — compressed context for handoff |
| Researcher | Web research — finds and synthesizes current information |
| Worker | General-purpose execution in an isolated context window |
Native Engine
Performance-critical operations use a Rust N-API engine:
- grep — ripgrep-backed content search
- glob — gitignore-aware file discovery
- ps — cross-platform process tree management
- highlight — syntect-based syntax highlighting
- ast — structural code search via ast-grep
- diff — fuzzy text matching and unified diff generation
- text — ANSI-aware text measurement and wrapping
- html — HTML-to-Markdown conversion
- image — decode, encode, resize images
- fd — fuzzy file path discovery
- clipboard — native clipboard access
- git — libgit2-backed git read operations (v2.16+)
- parser — GSD file parsing and frontmatter extraction
Dispatch Pipeline
The auto mode dispatch pipeline:
1. Read disk state (STATE.md, roadmap, plans)
2. Determine next unit type and ID
3. Classify complexity → select model tier
4. Apply budget pressure adjustments
5. Check routing history for adaptive adjustments
6. Dynamic model routing (if enabled) → select cheapest model for tier
7. Resolve effective model (with fallbacks)
8. Check pending captures → triage if needed
9. Build dispatch prompt (applying inline level compression)
10. Create fresh agent session
11. Inject prompt and let LLM execute
12. On completion: snapshot metrics, verify artifacts, persist state
13. Loop to step 1
Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched.
Key Modules (v2.24)
| Module | Purpose |
|---|---|
auto.ts | Auto-mode state machine and orchestration |
auto-dispatch.ts | Declarative dispatch table (phase → unit mapping) |
auto-prompts.ts | Prompt builders with inline level compression |
auto-worktree.ts | Worktree lifecycle (create, enter, merge, teardown) |
complexity-classifier.ts | Unit complexity classification (light/standard/heavy) |
model-router.ts | Dynamic model routing with cost-aware selection |
model-cost-table.ts | Built-in per-model cost data for cross-provider comparison |
routing-history.ts | Adaptive learning from routing outcomes |
captures.ts | Fire-and-forget thought capture and triage classification |
triage-resolution.ts | Capture resolution (inject, defer, replan, quick-task) |
visualizer-overlay.ts | Workflow visualizer TUI overlay |
visualizer-data.ts | Data loading for visualizer tabs |
visualizer-views.ts | Tab renderers (progress, deps, metrics, timeline, discussion status) |
metrics.ts | Token and cost tracking ledger |
state.ts | State derivation from disk |
preferences.ts | Preference loading, merging, validation |
git-service.ts | Git operations — commit, merge, worktree sync, completed-units cross-boundary sync |
memory-extractor.ts | Extract reusable knowledge from session transcripts |
memory-store.ts | Persistent memory store for cross-session knowledge |
queue-order.ts | Milestone queue ordering |