Architecture Overview

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

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.

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 with form intelligence 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

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. Resolve effective model (with fallbacks)
7. Build dispatch prompt (applying inline level compression)
8. Create fresh agent session
9. Inject prompt and let LLM execute
10. On completion: snapshot metrics, verify artifacts, persist state
11. 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.

4.9 KiB Raw Blame History