### Start and Configure GSD

Source: https://opengsd.net/docs/v2/getting-started

Initializes the GSD session and launches the setup wizard for provider and preference configuration.

```bash
gsd
```

```bash
/gsd config
```

--------------------------------

### Install and Start Ollama

Source: https://opengsd.net/docs/v2/providers

Commands to install and initiate the Ollama service on macOS.

```bash
# macOS
brew install ollama
ollama serve

# Or download from https://ollama.com
```

--------------------------------

### Run MCP Quickstart Script

Source: https://opengsd.net/docs/v5/mcp

Execute the quickstart script to generate tailored configuration for specific clients.

```bash
./scripts/mcp-quickstart.sh cursor     # or: claude, vscode, generic
```

--------------------------------

### Install GSD Browser and Codex Plugin

Source: https://opengsd.net/docs/v5/commands

Uses the installation script to set up the CLI and register the Codex plugin automatically.

```bash
curl -fsSL https://raw.githubusercontent.com/open-gsd/gsd-browser/main/install.sh | bash -s -- --codex-plugin
```

--------------------------------

### Build GSD Browser from source

Source: https://opengsd.net/docs/v5/commands

Clones the repository and installs the CLI using cargo.

```bash
git clone https://github.com/open-gsd/gsd-browser.git
cd gsd-browser
cargo install --path cli
```

--------------------------------

### Create a Task

Source: https://opengsd.net/docs/v2/getting-started

Executes a quick task or starts an interactive session for planned work.

```bash
gsd
```

```bash
/gsd quick "Update the README with local setup instructions"
```

--------------------------------

### Start Auto Mode

Source: https://opengsd.net/docs/v2/auto-mode

Initiates the auto-mode process.

```bash
/gsd auto
```

--------------------------------

### Launch GSD

Source: https://opengsd.net/docs/v2/providers

Command to start the GSD application.

```bash
gsd
```

--------------------------------

### Review configuration JSON example

Source: https://opengsd.net/docs/v1/configuration

A sample JSON configuration object defining specific models for Gemini and Qwen reviewers.

```json
{
  "review": {
    "models": {
      "gemini": "gemini-2.5-pro",
      "qwen": "qwen-max"
    }
  }
}
```

--------------------------------

### Initialize GSD in a Project

Source: https://opengsd.net/docs/v2/getting-started

Navigates to the target repository and starts GSD to create local project state tracking.

```bash
cd path/to/your-project
```

```bash
gsd
```

--------------------------------

### Install GSD Browser via npm

Source: https://opengsd.net/docs/v5/commands

Installs the GSD Browser package globally using npm.

```bash
npm install -g @opengsd/gsd-browser
```

--------------------------------

### Install GSD Pi

Source: https://opengsd.net/docs/v2/getting-started

Various methods to install the GSD Pi package globally or via npx.

```bash
npx @opengsd/gsd-pi@latest
```

```bash
npm install -g @opengsd/gsd-pi@latest
```

```bash
pnpm setup
exec $SHELL -l
pnpm add -g @opengsd/gsd-pi@latest
```

```bash
npx @opengsd/gsd-pi@latest --yes
```

--------------------------------

### Full Configuration Example

Source: https://opengsd.net/docs/v2/configuration

A complete YAML configuration file demonstrating all available settings including model selection, budget enforcement, and system hooks.

```yaml
---
version: 1

# Model selection
models:
  research: openrouter/deepseek/deepseek-r1
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  execution_simple: claude-haiku-4-5-20250414
  completion: claude-sonnet-4-6

# Token optimization
token_profile: balanced

# Dynamic model routing
dynamic_routing:
  enabled: true
  escalate_on_failure: true
  budget_pressure: true

# Budget
budget_ceiling: 25.00
budget_enforcement: pause
context_pause_threshold: 80

# Supervision
auto_supervisor:
  soft_timeout_minutes: 15
  hard_timeout_minutes: 25

# Git
git:
  auto_push: true
  merge_strategy: squash
  isolation: none             # "none" (default), "worktree", or "branch"
  commit_docs: true

# Skills
skill_discovery: suggest
skill_staleness_days: 60     # Skills unused for N days get deprioritized (0 = disabled)
always_use_skills:
  - debug-like-expert
skill_rules:
  - when: task involves authentication
    use: [clerk]

# Notifications
notifications:
  on_complete: false
  on_milestone: true
  on_attention: true

# Visualizer
auto_visualize: true

# Service tier
service_tier: priority         # "priority" or "flex" (for /gsd fast)

# Diagnostics
forensics_dedup: true          # deduplicate before filing forensics issues
show_token_cost: true          # show per-prompt cost in footer

# Hooks
post_unit_hooks:
  - name: code-review
    after: [execute-task]
    prompt: "Review {sliceId}/{taskId} for quality and security."
    artifact: REVIEW.md
---
```

--------------------------------

### Verify System Prerequisites

Source: https://opengsd.net/docs/v2/getting-started

Check the installed versions of Node.js, npm, and Git to ensure they meet the minimum requirements.

```bash
node --version
npm --version
git --version
```

--------------------------------

### Run MCP Server

Source: https://opengsd.net/docs/v5/mcp

Command to start the MCP server using JSON-RPC over stdio.

```bash
# Run the MCP server (JSON-RPC over stdio — most clients manage the process)
gsd-browser mcp
```

--------------------------------

### Start MCP Server

Source: https://opengsd.net/docs/v5/commands

Initializes the gsd-browser MCP server for use with AI agent platforms.

```bash
gsd-browser mcp
```

--------------------------------

### Setup pnpm global bin

Source: https://opengsd.net/docs/v2/troubleshooting

Configure pnpm to correctly manage the global bin directory in your PATH.

```bash
pnpm setup
exec $SHELL -l
pnpm add -g @opengsd/gsd-pi@latest
```

--------------------------------

### Install Graphify Hooks

Source: https://opengsd.net/docs/v1/configuration

Installs the git merge driver and post-commit rebuild hook for multi-developer graph synchronization.

```bash
graphify hook install
```

--------------------------------

### Manage Interactive Workbench Sessions

Source: https://opengsd.net/docs/v5/commands

Commands for starting, controlling, and configuring the interactive browser workbench.

```bash
gsd-browser view
gsd-browser view --print-only
gsd-browser control-state
gsd-browser takeover
gsd-browser release-control
gsd-browser sensitive-on
gsd-browser sensitive-off
```

--------------------------------

### Execution Context Output

Source: https://opengsd.net/docs/v1/configuration

Example output from the resolve-execution command showing the resolved configuration for an agent.

```json
{
  "model":             "opus",
  "profile":           "balanced",
  "effort":            "xhigh",
  "effort_rendered":   "xhigh",
  "effort_param":      "output_config.effort",
  "effort_propagation": "frontmatter",
  "fast_mode":         false,
  "fast_mode_supported": false
}
```

--------------------------------

### GSD Browser Quick Start Commands

Source: https://opengsd.net/docs/v5/commands

Common CLI commands for navigating pages, interacting with elements, and capturing browser state.

```bash
# Navigate to a page
gsd-browser navigate https://example.com

# Snapshot interactive elements and assign refs like @v1:e1
gsd-browser snapshot

# On example.com the only interactive element is the "More information..." link
gsd-browser click-ref @v1:e1

# Wait for navigation and assert the result
gsd-browser wait-for --condition network_idle
gsd-browser assert --checks '[{"kind":"url_contains","text":"iana.org"}]'

# Capture a PNG
gsd-browser screenshot --output page.png --format png
```

--------------------------------

### Start GSD as an MCP server

Source: https://opengsd.net/docs/v2/commands

Exposes GSD tools to MCP-compatible clients via stdin/stdout.

```bash
# Start GSD as an MCP server
gsd --mode mcp
```

--------------------------------

### Configure Codex Runtime

Source: https://opengsd.net/docs/v1/configuration

Example of a minimal configuration for the Codex runtime using a balanced profile.

```json
{
  "runtime": "codex",
  "model_profile": "balanced"
}
```

--------------------------------

### Configure Claude Runtime

Source: https://opengsd.net/docs/v1/configuration

Example of a minimal configuration for the Claude runtime using a quality profile.

```json
{
  "runtime": "claude",
  "model_profile": "quality"
}
```

--------------------------------

### Manage Cloud MCP Gateway

Source: https://opengsd.net/docs/v2/commands

Commands for starting the HTTP gateway and managing local runtime connections.

```bash
GSD_CLOUD_USER_TOKEN="replace-with-a-long-random-token" gsd-cloud-mcp-gateway --port 8787
gsd-daemon cloud status
gsd-daemon cloud pair --gateway "https://gateway.example.com" --code "PAIRING_CODE" --runtime-name "Laptop"
gsd-daemon cloud connect --verbose
gsd-daemon cloud disconnect
```

--------------------------------

### Install terminal-notifier for macOS

Source: https://opengsd.net/docs/v2/troubleshooting

Install the terminal-notifier utility to enable desktop notifications on macOS.

```bash
brew install terminal-notifier
```

--------------------------------

### Example Worktree Hook Script

Source: https://opengsd.net/docs/v2/configuration

A sample bash script for copying environment files and symlinking assets into a newly created worktree.

```bash
#!/bin/bash
# Copy environment files and symlink assets into the new worktree
cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
cp "$SOURCE_DIR/.env.local" "$WORKTREE_DIR/.env.local" 2>/dev/null || true
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"
```

--------------------------------

### Configure gsd-browser via TOML

Source: https://opengsd.net/docs/v5/commands

Example configuration file for defining browser, daemon, screenshot, settle, log, artifact, and timeline settings.

```toml
[browser]
path = "/usr/bin/chromium"
cdp_url = "http://localhost:9222"   # attach to existing Chrome instead of launching
headless = true

[daemon]
port = 9222
host = "127.0.0.1"

[screenshot]
quality = 90
format = "png"
full_page = false

[settle]
timeout_ms = 500
poll_ms = 40
quiet_window_ms = 100

[logs]
max_buffer_size = 1000

[artifacts]
dir = "./browser-artifacts"

[timeline]
enabled = true
max_entries = 500
```

--------------------------------

### Verify Installation and Path

Source: https://opengsd.net/docs/v2/getting-started

Confirm the gsd command is available and locate the global npm bin directory if troubleshooting PATH issues.

```bash
gsd
```

```bash
npm prefix -g
```

--------------------------------

### Troubleshooting GSD

Source: https://opengsd.net/docs/v2/getting-started

Commands to diagnose setup issues, verify provider credentials, or recover from stuck sessions.

```bash
gsd
```

```bash
/gsd doctor
```

```bash
/gsd config
```

```bash
/gsd status
```

--------------------------------

### Configure Default Reviewers

Source: https://opengsd.net/docs/v1/configuration

Example configuration for setting default reviewers for the /gsd-review command.

```json
{
  "review": {
    "default_reviewers": ["gemini", "codex"]
  }
}
```

--------------------------------

### Fast Mode Configuration

Source: https://opengsd.net/docs/v1/configuration

Example JSON configuration for enabling or disabling fast mode across different agent tiers.

```json
{
  "fast_mode": {
    "enabled": false,
    "routing_tier_defaults": {
      "light":    true,
      "standard": false,
      "heavy":    false
    },
    "agent_overrides": {}
  }
}
```

--------------------------------

### Headless Mode Execution Examples

Source: https://opengsd.net/docs/v2/commands

Various commands for running GSD in headless mode, including auto-mode, unit execution, and context handling.

```bash
# Run auto mode (default)
gsd headless

# Run a single unit
gsd headless next

# Instant JSON snapshot — no LLM, ~50ms
gsd headless query

# With timeout for CI
gsd headless --timeout 600000 auto

# Force a specific phase
gsd headless dispatch plan

# Create a new milestone from a context file and start auto mode
gsd headless new-milestone --context brief.md --auto

# Create a milestone from inline text
gsd headless new-milestone --context-text "Build a REST API with auth"

# Pipe context from stdin
echo "Build a CLI tool" | gsd headless new-milestone --context -
```

--------------------------------

### Set Ollama host configuration

Source: https://opengsd.net/docs/v1/configuration

Example command to override the default Ollama server host URL.

```bash
gsd config-set review.ollama_host http://192.168.1.10:11434
```

--------------------------------

### Effort Control Configuration

Source: https://opengsd.net/docs/v1/configuration

Example JSON configuration for defining global, tier-based, and agent-specific reasoning effort levels.

```json
{
  "effort": {
    "default": "high",
    "routing_tier_defaults": {
      "light":    "low",
      "standard": "high",
      "heavy":    "xhigh"
    },
    "agent_overrides": {
      "gsd-planner": "max"
    }
  }
}
```

--------------------------------

### Define Per-Runtime Overrides

Source: https://opengsd.net/docs/v1/configuration

Example of overriding default tier mappings for a specific runtime.

```json
{
  "runtime": "codex",
  "model_profile": "quality",
  "model_profile_overrides": {
    "codex": {
      "opus": "gpt-5-pro",
      "haiku": { "model": "gpt-5-nano", "reasoning_effort": "low" }
    }
  }
}
```

--------------------------------

### Set Ollama model configuration

Source: https://opengsd.net/docs/v1/configuration

Example command to set a specific model tag for the Ollama reviewer.

```bash
gsd config-set review.models.ollama codellama
```

--------------------------------

### Extension Management Commands

Source: https://opengsd.net/docs/v2/commands

Commands for listing, enabling, disabling, installing, and managing GSD extensions.

```APIDOC
## /gsd extensions list
### Description
List all extensions and their status. User-installed entries show [user] plus the install source.

## /gsd extensions enable <id>
### Description
Enable a disabled extension.

## /gsd extensions disable <id>
### Description
Disable an extension.

## /gsd extensions info <id>
### Description
Show extension details.

## /gsd extensions install <spec>
### Description
Install a user extension. <spec> is an npm package, a git URL, or a local path. Restart GSD to activate.

## /gsd extensions uninstall <id>
### Description
Remove a user-installed extension. Warns if other extensions depend on it.

## /gsd extensions update [id]
### Description
Update a single user-installed npm extension to its latest version, or all of them when id is omitted.

## /gsd extensions validate <path>
### Description
Validate an extension package directory against the manifest schema before publishing or installing.
```

--------------------------------

### Headless Query and Inspection

Source: https://opengsd.net/docs/v2/commands

Examples of querying the GSD state using headless mode and filtering output with jq.

```bash
gsd headless query | jq '.state.phase'
# "executing"

gsd headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}

gsd headless query | jq '.cost.total'
# 4.25
```

--------------------------------

### Upgrade GSD

Source: https://opengsd.net/docs/v2/getting-started

Updates the GSD installation to the latest release.

```bash
gsd upgrade
```

--------------------------------

### Perform In-Session Update

Source: https://opengsd.net/docs/v2/commands

Checks for and installs GSD updates without exiting the current session.

```bash
/gsd update
# Current version: v2.36.0
# Checking npm registry...
# Updated to v2.37.0. Restart GSD to use the new version.
```

--------------------------------

### Upgrade GSD-pi package

Source: https://opengsd.net/docs/v2/troubleshooting

Commands to remove legacy global packages and install the latest scoped version.

```bash
sudo npm uninstall -g gsd-pi
rm -f ~/.gsd/.update-check ~/.gsd/agent/managed-resources.json
sudo npm install -g @opengsd/gsd-pi@latest
```

```powershell
Remove-Item "$env:USERPROFILE\.gsd\.update-check" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.gsd\agent\managed-resources.json" -Force -ErrorAction SilentlyContinue
npm install -g @opengsd/gsd-pi@latest
```

```bash
npx @opengsd/gsd-pi@latest
```

--------------------------------

### Terminate web server process

Source: https://opengsd.net/docs/v2/troubleshooting

Kill an existing process running on port 3000 if web mode fails to start.

```bash
lsof -ti:3000 | xargs kill
```

--------------------------------

### Manual MCP Server Configuration

Source: https://opengsd.net/docs/v2/providers

Define the GSD MCP server in your .mcp.json file using either local npx or global installation.

```json
{
  "mcpServers": {
    "gsd": {
      "command": "npx",
      "args": ["gsd-mcp-server"],
      "env": {
        "GSD_CLI_PATH": "/path/to/gsd"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "gsd": {
      "command": "gsd-mcp-server"
    }
  }
}
```

--------------------------------

### Check Git Status

Source: https://opengsd.net/docs/v2/getting-started

Verify the state of the repository before starting work or checking local project state.

```bash
git status
```

```bash
git status --short
```

--------------------------------

### Configure Model-Specific MCP Access

Source: https://opengsd.net/docs/v2/configuration

Example configuration restricting Haiku models to specific tools while excluding noisy servers from Sonnet models.

```yaml
claude_code_mcp:
  per_model:
    claude-haiku-4-5:
      allowed_servers:
        - google-search
      # gsd-workflow is allowed implicitly; no need to list it.
    claude-sonnet-4-6:
      blocked_servers:
        - analytics-noisy
```

--------------------------------

### Configure vLLM in models.json

Source: https://opengsd.net/docs/v2/providers

Configuration structure for vLLM. The model ID must match the --model flag used when starting the vLLM server.

```json
{
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "api": "openai-completions",
      "apiKey": "vllm",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsUsageInStreaming": false
      },
      "models": [
        {
          "id": "meta-llama/Llama-3.1-8B-Instruct",
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}
```

--------------------------------

### Configure global PATH for GSD

Source: https://opengsd.net/docs/v2/troubleshooting

Add the npm global bin directory to your shell PATH if the gsd command is not found after installation.

```bash
npm prefix -g
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Configure provider via onboarding wizard

Source: https://opengsd.net/docs/v2/providers

Use the CLI wizard to automatically generate the provider configuration.

```bash
gsd config
# Choose "Paste an API key" → "Custom (OpenAI-compatible)"
# Enter: base URL, API key, model ID
```

--------------------------------

### Conventional Commit Format with GSD Metadata

Source: https://opengsd.net/docs/v2/git-strategy

Example of the required commit message format using conventional commits and GSD-Task trailers.

```text
feat: core type definitions

GSD-Task: M001/S01/T01

feat: markdown parser for plan files

GSD-Task: M001/S01/T02
```

--------------------------------

### Run the Migration Command

Source: https://opengsd.net/docs/v2/migration

Execute the migration tool from the project root or by specifying a target directory path.

```bash
# From within the project directory
/gsd migrate

# Or specify a path
/gsd migrate ~/projects/my-old-project
```

--------------------------------

### Enable Automatic Pull Requests

Source: https://opengsd.net/docs/v2/git-strategy

Configure GSD to automatically create a pull request upon milestone completion. Requires the 'gh' CLI to be installed and authenticated.

```yaml
git:
  auto_push: true
  auto_pr: true
  pr_target_branch: develop
```

--------------------------------

### Build with Alternative Backends

Source: https://opengsd.net/docs/v5/commands

Builds the CLI tool with specific feature flags to enable alternative browser backends.

```bash
cargo install --path cli --no-default-features --features chromey-backend
# or for full stealth
cargo install --path cli --no-default-features --features stealth
```

--------------------------------

### Define Per-Agent Model Overrides

Source: https://opengsd.net/docs/v1/configuration

Override default model assignments for specific agents within a profile. Changes require running 'gsd install <runtime>' to take effect on certain platforms.

```json
{
  "model_profile": "balanced",
  "model_overrides": {
    "gsd-executor": "opus",
    "gsd-planner": "haiku"
  }
}
```

--------------------------------

### Configure Global API Keys

Source: https://opengsd.net/docs/v2/configuration

Run this command to open the interactive wizard for managing global tool API keys.

```bash
/gsd config
```

--------------------------------

### Handle Annotations and Recordings

Source: https://opengsd.net/docs/v5/commands

Commands for managing local annotation state and recording browser activity bundles.

```bash
gsd-browser annotations
gsd-browser annotation-get <id>
gsd-browser annotation-clear <id>
gsd-browser annotation-resolve <id>
gsd-browser annotation-export --output annotations.json

gsd-browser record-start --name checkout-bug
gsd-browser record-stop
gsd-browser recordings
gsd-browser recording-get <id>
gsd-browser recording-export <id> --output <path>
gsd-browser recording-discard <id>
gsd-browser recording-validate <id-or-path> --json
```

--------------------------------

### Configure Groq API Key

Source: https://opengsd.net/docs/v2/providers

Set the GROQ_API_KEY environment variable to authenticate with Groq.

```bash
export GROQ_API_KEY="gsk_..."
```

--------------------------------

### Build and Test MCP Server

Source: https://opengsd.net/docs/v5/mcp

Commands for building the project, performing a manual protocol smoke test, and running end-to-end tests with a browser.

```bash
# Build
cargo build -p gsd-browser

# Manual protocol smoke
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n' | ./target/debug/gsd-browser mcp

# End-to-end with real browser
python3 scripts/test-mcp.py
```

--------------------------------

### Enable Qwen thinking mode

Source: https://opengsd.net/docs/v2/providers

Configure compatibility settings to enable thinking mode for Qwen-compatible servers.

```json
{
  "compat": {
    "thinkingFormat": "qwen",
    "supportsDeveloperRole": false
  }
}
```

--------------------------------

### Define runtime context

Source: https://opengsd.net/docs/v2/configuration

Declare project-level environment information in .gsd/RUNTIME.md to be inlined into prompts.

```markdown
# Runtime Context

## API Endpoints
- Main API: https://api.example.com
- Cache: redis://localhost:6379

## Environment Variables
- DEPLOYMENT_ENV: staging
- DB_POOL_SIZE: 20

## Local Services
- PostgreSQL: localhost:5432
- Redis: localhost:6379
```

--------------------------------

### Configure Google Gemini API Key

Source: https://opengsd.net/docs/v2/providers

Set the GEMINI_API_KEY environment variable to authenticate with Google Gemini.

```bash
export GEMINI_API_KEY="..."
```

--------------------------------

### Configure xAI API Key

Source: https://opengsd.net/docs/v2/providers

Set the XAI_API_KEY environment variable to authenticate with xAI.

```bash
export XAI_API_KEY="xai-..."
```

--------------------------------

### Run Auto Mode

Source: https://opengsd.net/docs/v2/getting-started

Enables automated planning and implementation for well-defined tasks.

```bash
gsd
```

```bash
/gsd auto
```

--------------------------------

### Visualize Workflow

Source: https://opengsd.net/docs/v2/auto-mode

Opens the interactive workflow visualizer.

```bash
/gsd visualize
```

--------------------------------

### Configure Mistral API Key

Source: https://opengsd.net/docs/v2/providers

Set the MISTRAL_API_KEY environment variable to authenticate with Mistral.

```bash
export MISTRAL_API_KEY="..."
```

--------------------------------

### Initialize GSD MCP Configuration

Source: https://opengsd.net/docs/v2/providers

Trigger the automatic creation or update of the project's .mcp.json file.

```bash
/gsd mcp init
```

--------------------------------

### Configure Allowed URLs in settings.json

Source: https://opengsd.net/docs/v2/configuration

Add hostnames or IP addresses to the fetchAllowedUrls array in the global settings file to bypass default URL blocking.

```json
{
  "fetchAllowedUrls": ["internal-docs.company.com", "192.168.1.50"]
}
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://opengsd.net/docs/v5/mcp

Configuration snippet for adding gsd-browser to Claude Desktop.

```json
{
  "mcpServers": {
    "gsd-browser": {
      "command": "gsd-browser",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Configure GitHub Copilot

Source: https://opengsd.net/docs/v2/providers

Use the GSD configuration command to sign in to GitHub Copilot via the browser.

```bash
gsd config
# Choose "Sign in with your browser" → "GitHub Copilot"
```

--------------------------------

### Set custom instructions

Source: https://opengsd.net/docs/v2/configuration

Define durable instructions that are appended to every session.

```yaml
custom_instructions:
  - "Always use TypeScript strict mode"
  - "Prefer functional patterns over classes"
```

--------------------------------

### Configure Multi-Repository Workspace

Source: https://opengsd.net/docs/v2/configuration

Sets up a parent workspace to manage multiple child repositories with specific paths and verification policies.

```yaml
workspace:
  mode: parent                  # "project" (default) or "parent"
  repositories:
    frontend:
      path: frontend            # relative to project root (or absolute path within project root)
      role: ui                  # optional
      verification:             # optional default verification commands
        - npm run test
      commit_policy: auto       # optional: "auto" or "skip"
    backend:
      path: backend
```

--------------------------------

### Enable Audit Trail via Configuration

Source: https://opengsd.net/docs/v1/configuration

Enable the audit trail by setting the audit.enabled property in the configuration file.

```json
{
  "audit": {
    "enabled": true
  }
}
```

--------------------------------

### Check available models

Source: https://opengsd.net/docs/v2/providers

Command to list all models currently recognized by the provider.

```text
/model
```

--------------------------------

### Configure Agent Skills in JSON

Source: https://opengsd.net/docs/v1/configuration

Define agent types and their associated skill directory paths in the .planning/config.json file.

```json
{
  "agent_skills": {
    "gsd-executor": ["skills/testing-standards", "skills/api-conventions"],
    "gsd-planner": ["skills/architecture-rules"],
    "gsd-verifier": ["skills/acceptance-criteria"]
  }
}
```

--------------------------------

### Configure OpenRouter API Key

Source: https://opengsd.net/docs/v2/providers

Set the OPENROUTER_API_KEY environment variable to authenticate with OpenRouter.

```bash
export OPENROUTER_API_KEY="sk-or-..."
```

--------------------------------

### Enable Deep Planning Mode in Preferences

Source: https://opengsd.net/docs/v2/auto-mode

Set the planning depth to deep within the project preferences file.

```yaml
planning_depth: deep

```

--------------------------------

### Configure stdio MCP Server

Source: https://opengsd.net/docs/v2/configuration

Define a local MCP server using the stdio transport by specifying the command and arguments.

```json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "/absolute/path/to/python3",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "API_URL": "http://localhost:8000"
      }
    }
  }
}
```

--------------------------------

### Configure models by phase type

Source: https://opengsd.net/docs/v1/configuration

Define model tiers for specific project phases within the configuration block.

```json
{
  "model_profile": "balanced",
  "models": {
    "planning": "opus",
    "discuss": "opus",
    "research": "sonnet",
    "execution": "opus",
    "verification": "sonnet",
    "completion": "sonnet"
  },
  "model_overrides": {
    "gsd-codebase-mapper": "haiku"
  }
}
```

--------------------------------

### Configure model fallbacks

Source: https://opengsd.net/docs/v2/troubleshooting

Define execution models and fallback options in your configuration.

```yaml
models:
  execution:
    model: claude-sonnet-4-6
    fallbacks:
      - openrouter/minimax/minimax-m2.5
```

--------------------------------

### Configure Multi-Repository Workspace

Source: https://opengsd.net/docs/v2/configuration

Sets up a parent workspace to coordinate multiple child repositories with specific roles and commit policies.

```yaml
workspace:
  mode: parent
  repositories:
    frontend:
      path: apps/frontend
      role: web
      verification:
        - pnpm -C apps/frontend test
      commit_policy: auto
    backend:
      path: services/backend
      role: api
      verification:
        - pnpm -C services/backend test
      commit_policy: skip
```

--------------------------------

### Recover Project Database

Source: https://opengsd.net/docs/v2/migration

Reconstruct the project hierarchy from existing markdown files if the database is missing or damaged.

```bash
/gsd recover
```

--------------------------------

### Configure Anthropic API Key

Source: https://opengsd.net/docs/v2/providers

Set the environment variable to authenticate with Anthropic models.

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Wave Execution Model Analysis

Source: https://opengsd.net/docs/v1/architecture

Visual representation of how plans are grouped into dependency waves for parallel execution.

```text
Wave Analysis:
  Plan 01 (no deps)      ─┐
  Plan 02 (no deps)      ─┤── Wave 1 (parallel)
  Plan 03 (depends: 01)  ─┤── Wave 2 (waits for Wave 1)
  Plan 04 (depends: 02)  ─┘
  Plan 05 (depends: 03,04) ── Wave 3 (waits for Wave 2)
```

--------------------------------

### Configure Anthropic on Vertex AI

Source: https://opengsd.net/docs/v2/providers

Authenticate using Google Cloud Application Default Credentials and set the project ID.

```bash
gcloud auth application-default login
export ANTHROPIC_VERTEX_PROJECT_ID="my-project-id"
```

--------------------------------

### Set Dummy API Key

Source: https://opengsd.net/docs/v2/providers

Provide a placeholder value for local servers that do not require authentication.

```json
"apiKey": "not-needed"
```

--------------------------------

### Configure Azure OpenAI API Key

Source: https://opengsd.net/docs/v2/providers

Set the AZURE_OPENAI_API_KEY environment variable to authenticate with Azure OpenAI.

```bash
export AZURE_OPENAI_API_KEY="..."
```

--------------------------------

### Generate Milestone Reports

Source: https://opengsd.net/docs/v2/commands

Creates HTML reports for milestones and opens the index in a browser.

```bash
# Generate all missing milestone reports and open the reports index
/gsd report

# Generate HTML report for the active milestone
/gsd report --html

# Generate retrospective reports for ALL milestones at once
/gsd report --html --all
```

--------------------------------

### Configure Quick-Task Branching Template

Source: https://opengsd.net/docs/v1/configuration

Sets the branch naming convention for quick tasks using the quick_branch_template setting.

```json
"git": {
  "quick_branch_template": "gsd/quick-{num}-{slug}"
}
```

--------------------------------

### Configure per-phase model selection

Source: https://opengsd.net/docs/v2/configuration

Define models for specific agent phases using YAML. Each key supports a direct model string or an object with fallback configurations.

```yaml
models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  execution_simple: claude-haiku-4-5-20250414
  completion: claude-sonnet-4-6
  subagent: claude-sonnet-4-6
```

--------------------------------

### Configure OpenAI API Key

Source: https://opengsd.net/docs/v2/providers

Set the OPENAI_API_KEY environment variable to authenticate with OpenAI services.

```bash
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Configure LM Studio in models.json

Source: https://opengsd.net/docs/v2/providers

Configuration structure for integrating LM Studio. Ensure the model ID matches the identifier shown in the LM Studio server tab.

```json
{
  "providers": {
    "lm-studio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "your-model-name",
          "name": "My Local Model",
          "contextWindow": 32768,
          "maxTokens": 4096
        }
      ]
    }
  }
}
```

--------------------------------

### Verify Ollama Server and Models

Source: https://opengsd.net/docs/v2/providers

Check server connectivity and ensure the required model is pulled locally.

```bash
# Verify the server is running
curl http://localhost:11434/v1/models

# Pull the model if missing
ollama pull llama3.1:8b
```

--------------------------------

### Execute GSD Brief Command

Source: https://opengsd.net/docs/v2/commands

Syntax for invoking the brief command with a specified mode and optional topic or slide flag.

```bash
/gsd brief <diagram|plan|diff|recap|table|slides> [topic] [--slides]
```

--------------------------------

### Define Git Preferences

Source: https://opengsd.net/docs/v2/git-strategy

Configure granular Git behavior settings such as push policies, branch management, and isolation strategies.

```yaml
git:
  auto_push: false            # push after commits
  push_branches: false        # push milestone branch
  remote: origin
  snapshots: false            # WIP snapshot commits
  pre_merge_check: false      # pre-merge validation
  commit_type: feat           # override commit type prefix
  main_branch: main           # primary branch name
  commit_docs: true           # commit .gsd/ to git
  isolation: none             # "none" (default), "worktree", or "branch"
  auto_pr: false              # create PR on milestone completion
  pr_target_branch: develop   # PR target branch (default: main)
```

--------------------------------

### Verify MCP Server Configuration

Source: https://opengsd.net/docs/v2/configuration

Use these commands within a GSD session to verify that your MCP server is correctly configured and responsive.

```text
mcp_servers
mcp_discover(server="my-server")
mcp_call(server="my-server", tool="<tool_name>", args={...})
```

--------------------------------

### Configure Worktree Post-Create Hook

Source: https://opengsd.net/docs/v2/configuration

Defines the path to a script executed automatically after a worktree is created.

```yaml
git:
  worktree_post_create: .gsd/hooks/post-worktree-create
```

--------------------------------

### Override configuration via environment variables

Source: https://opengsd.net/docs/v5/commands

Use the GSD_BROWSER_<SECTION>_<FIELD> naming convention to override TOML settings via environment variables.

```bash
export GSD_BROWSER_BROWSER_PATH=/usr/bin/chromium
export GSD_BROWSER_BROWSER_CDP_URL=http://localhost:9222
export GSD_BROWSER_BROWSER_HEADLESS=true
export GSD_BROWSER_DAEMON_PORT=9333
export GSD_BROWSER_SCREENSHOT_QUALITY=90
export GSD_BROWSER_SETTLE_TIMEOUT_MS=1000
export GSD_BROWSER_ARTIFACTS_DIR=./browser-artifacts
export GSD_BROWSER_VAULT_KEY=your-encryption-key
```

--------------------------------

### Configure feature flags using gsd-tools

Source: https://opengsd.net/docs/v1/configuration

Use the config-set command to enable or disable features dynamically. The features.* namespace accepts any key matching the pattern.

```bash
# Enable a feature
gsd-tools query config-set features.global_learnings true

# Disable a feature
gsd-tools query config-set features.thinking_partner false
```

--------------------------------

### Implement a Reliable Login Flow

Source: https://opengsd.net/docs/v5/agent-best-practices

A standard sequence for authenticating, verifying the session, and persisting the state for future reuse.

```pseudo-code
browser_navigate(login_url)
browser_act("accept_cookies")  // if relevant
browser_act("fill_email") or browser_fill_form
browser_act("fill_password")
browser_act("submit_form")
browser_wait_for network_idle or url_contains dashboard
browser_assert [checks for logged-in state]
browser_save_state("myapp-auth")   // for future reuse
```

--------------------------------

### Validate models.json

Source: https://opengsd.net/docs/v2/providers

Command to verify the syntax of the models configuration file.

```bash
cat ~/.gsd/agent/models.json | python3 -m json.tool
```

--------------------------------

### Steer Auto Mode

Source: https://opengsd.net/docs/v2/auto-mode

Adjusts plan documents during execution without stopping the pipeline.

```bash
/gsd steer
```

--------------------------------

### Configure Allowed URLs via Environment Variable

Source: https://opengsd.net/docs/v2/configuration

Set the GSD_FETCH_ALLOWED_URLS environment variable to allow internal URLs; this takes precedence over the settings.json file.

```bash
export GSD_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50"
```

--------------------------------

### Enable Stealth Mode via CLI or Config

Source: https://opengsd.net/docs/v5/commands

Configures stealth mode using command-line flags or the browser configuration file.

```bash
gsd-browser --stealth navigate https://bot.sannysoft.com
# or
gsd-browser --backend stealth navigate ...
```

```toml
[browser]
stealth = true
backend = "chaser-oxide"   # or "stealth", "chromey"
```

--------------------------------

### Enable UAT Dispatch

Source: https://opengsd.net/docs/v2/configuration

Enables automatic User Acceptance Test runs upon slice completion.

```yaml
uat_dispatch: true
```

--------------------------------

### Configure Cursor or VS Code MCP

Source: https://opengsd.net/docs/v5/mcp

Configuration snippet for adding gsd-browser to Cursor or VS Code MCP settings.

```json
{
  "mcpServers": {
    "gsd-browser": {
      "command": "gsd-browser",
      "args": ["mcp"],
      "env": {
        "GSD_BROWSER_BROWSER_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
        "GSD_BROWSER_VAULT_KEY": "your-strong-key-here"
      }
    }
  }
}
```

--------------------------------

### Authenticate via Claude Code CLI

Source: https://opengsd.net/docs/v2/providers

Use the official Claude Code CLI for authentication with subscription-based accounts.

```bash
# Install Claude Code CLI first, then sign in inside Claude Code.
claude
# Run /login if prompted or if you need to switch accounts, then start GSD.
gsd
```

--------------------------------

### Enable token cost display

Source: https://opengsd.net/docs/v2/configuration

Displays per-prompt and cumulative session token costs in the footer.

```yaml
show_token_cost: true    # default: false
```

--------------------------------

### Configure Amazon Bedrock Credentials

Source: https://opengsd.net/docs/v2/providers

Set AWS credentials or a bearer token to authenticate with Amazon Bedrock.

```bash
# Option 1: Named profile
export AWS_PROFILE="my-profile"

# Option 2: IAM keys
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# Option 3: Bedrock API key (bearer token)
export AWS_BEARER_TOKEN_BEDROCK="..."
```

--------------------------------

### Define Workspace Repositories

Source: https://opengsd.net/docs/v2/configuration

Configures repository targets and commit policies for project or parent workspaces.

```yaml
workspace:
  mode: parent   # "project" or "parent"
  repositories:
    frontend:
      path: frontend
      role: ui
      verification:
        - npm run test
      commit_policy: auto   # "auto" or "skip"
    backend:
      path: backend
```

--------------------------------

### Configure context management settings

Source: https://opengsd.net/docs/v2/configuration

Adjusts observation masking and tool result truncation to manage context usage.

```yaml
context_management:
  observation_masking: true          # replace old tool results with placeholders (default: true)
  observation_mask_turns: 8          # keep results from last N user turns (1-50, default: 8)
  compaction_threshold_percent: 0.70 # target compaction at 70% context usage (0.5-0.95, default: 0.70)
  tool_result_max_chars: 800         # cap individual tool result content (200-10000, default: 800)
```

--------------------------------

### Configure model fallbacks with provider targeting

Source: https://opengsd.net/docs/v2/configuration

Specify a list of fallback models to use if the primary model fails, with an optional provider override.

```yaml
models:
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
      - openrouter/moonshotai/kimi-k2.5
    provider: bedrock    # optional: target a specific provider
```

--------------------------------

### Configure Verification Settings

Source: https://opengsd.net/docs/v2/configuration

Defines shell commands for post-task verification and configures auto-fix retry behavior.

```yaml
verification_commands:
  - npm run lint
  - npm run test
verification_auto_fix: true       # auto-retry on failure (default: true)
verification_max_retries: 2       # max retry attempts (default: 2)
```

--------------------------------

### Manual Worktree Management Commands

Source: https://opengsd.net/docs/v2/git-strategy

Use these commands for standalone worktree operations in the CLI.

```text
/worktree create
/worktree switch
/worktree merge
/worktree remove
```

--------------------------------

### Enable automatic workflow visualization

Source: https://opengsd.net/docs/v2/configuration

Automatically displays the workflow visualizer upon milestone completion.

```yaml
auto_visualize: true
```

--------------------------------

### Enable Slice Discussion Gate

Source: https://opengsd.net/docs/v2/auto-mode

Pauses execution before each slice to allow for human review and confirmation.

```yaml
require_slice_discussion: true
```

--------------------------------

### Common GSD Commands

Source: https://opengsd.net/docs/v2/getting-started

A list of standard commands used during an interactive GSD session.

```bash
/gsd status
/gsd auto
/gsd next
/gsd stop
/gsd help
```

--------------------------------

### cmux Integration Commands

Source: https://opengsd.net/docs/v2/commands

Commands for managing cmux integration settings and preferences.

```APIDOC
## /gsd cmux status
### Description
Show cmux detection, prefs, and capabilities.

## /gsd cmux on
### Description
Enable cmux integration.

## /gsd cmux off
### Description
Disable cmux integration.

## /gsd cmux notifications on/off
### Description
Toggle cmux desktop notifications.

## /gsd cmux sidebar on/off
### Description
Toggle cmux sidebar metadata.

## /gsd cmux splits on/off
### Description
Toggle cmux visual subagent splits.
```

--------------------------------

### Agent Skills Prompt Injection Format

Source: https://opengsd.net/docs/v1/configuration

The structure of the injected skills block within the Task() prompt at agent spawn time.

```xml
<agent_skills>
Read these user-configured skills:
- @skills/testing-standards/SKILL.md
- @skills/api-conventions/SKILL.md
</agent_skills>
```

--------------------------------

### Verify Migration Integrity

Source: https://opengsd.net/docs/v2/migration

Run the doctor command to check database and projection integrity after migration.

```bash
/gsd doctor
```

--------------------------------

### Configure dynamic model routing

Source: https://opengsd.net/docs/v2/configuration

Enable and configure complexity-based model routing.

```yaml
dynamic_routing:
  enabled: true
  capability_routing: true          # score models by task capability (v2.59)
  tier_models:
    light: claude-haiku-4-5
    standard: claude-sonnet-4-6
    heavy: claude-opus-4-6
  escalate_on_failure: true
  budget_pressure: true
  cross_provider: true
```

--------------------------------

### Run GSD recovery commands

Source: https://opengsd.net/docs/v2/troubleshooting

Use these commands to fix derived state or recover the database from artifacts.

```bash
/gsd doctor fix
```

```bash
/gsd recover
```

```bash
gsd headless recover
```

--------------------------------

### Define situational skill rules

Source: https://opengsd.net/docs/v2/configuration

Configure conditional skill routing based on human-readable task triggers.

```yaml
skill_rules:
  - when: task involves authentication
    use: [clerk]
  - when: frontend styling work
    prefer: [frontend-design]
  - when: working with legacy code
    avoid: [aggressive-refactor]
```

--------------------------------

### gsd headless query

Source: https://opengsd.net/docs/v2/commands

Returns a single JSON object with the full project snapshot.

```APIDOC
## gsd headless query

### Description
Provides an instant (~50ms) JSON snapshot of the current GSD state without invoking an LLM session.

### Response Schema
- **state** (object) - Current phase, active milestones, slices, tasks, and progress.
- **next** (object) - The next scheduled action, unit type, and unit ID.
- **cost** (object) - Cost breakdown for workers and total cost.
```

--------------------------------

### Configure GitHub Sync

Source: https://opengsd.net/docs/v2/configuration

Defines the GitHub repository and project settings for automatic synchronization of milestones and tasks.

```yaml
github:
  enabled: true
  repo: "owner/repo"              # auto-detected from git remote if omitted
  labels: [gsd, auto-generated]   # labels applied to created issues/PRs
  project: "Project ID"           # optional GitHub Project board
```

--------------------------------

### Headless Recovery Command

Source: https://opengsd.net/docs/v2/commands

Resets the database hierarchy and state for non-interactive environments.

```bash
gsd headless recover
```

--------------------------------

### Configure HTTP MCP Server

Source: https://opengsd.net/docs/v2/configuration

Define an MCP server that communicates over an HTTP endpoint.

```json
{
  "mcpServers": {
    "my-http-server": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

--------------------------------

### Add custom headers to provider configuration

Source: https://opengsd.net/docs/v2/providers

Include additional headers required by proxies like LiteLLM within the provider definition.

```json
{
  "providers": {
    "litellm-proxy": {
      "baseUrl": "https://litellm.example.com/v1",
      "apiKey": "MY_API_KEY",
      "api": "openai-completions",
      "headers": {
        "x-custom-header": "value"
      },
      "models": [...]
    }
  }
}
```

--------------------------------

### Configure Auto Supervisor Timeouts

Source: https://opengsd.net/docs/v2/auto-mode

Define timeout thresholds in the preferences configuration to manage session duration and prevent runaway processes.

```yaml
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
```

--------------------------------

### Pull Ollama Models

Source: https://opengsd.net/docs/v2/providers

Commands to download specific models for use with Ollama.

```bash
ollama pull llama3.1:8b
ollama pull qwen2.5-coder:7b
```

--------------------------------

### Define GSD Preferences

Source: https://opengsd.net/docs/v2/configuration

Standard YAML frontmatter structure for configuring models, timeouts, and budget settings.

```yaml
---
version: 1
models:
  research: claude-sonnet-4-6
  planning: claude-opus-4-6
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30
budget_ceiling: 50.00
token_profile: balanced
---

```

--------------------------------

### Manage LSP status

Source: https://opengsd.net/docs/v2/troubleshooting

Check and reload the language server status.

```bash
lsp status
```

```bash
lsp reload
```

--------------------------------

### Configure Notifications

Source: https://opengsd.net/docs/v2/configuration

Enables and customizes the types of events that trigger desktop notifications.

```yaml
notifications:
  enabled: true
  on_complete: true           # notify on unit completion
  on_error: true              # notify on errors
  on_budget: true             # notify on budget thresholds
  on_milestone: true          # notify when milestone finishes
  on_attention: true          # notify when manual attention needed
```

--------------------------------

### Run GSD diagnostic and repair

Source: https://opengsd.net/docs/v2/troubleshooting

Use these commands to identify and fix issues with the .gsd/ directory, references, and worktree health.

```bash
/gsd doctor
```

```bash
/gsd doctor fix
```

```bash
/gsd auto
```

--------------------------------

### Configure Streaming Usage Compatibility

Source: https://opengsd.net/docs/v2/providers

Disable usage reporting in streaming for servers that do not support the include_usage option.

```json
{
  "compat": {
    "supportsUsageInStreaming": false
  }
}
```

--------------------------------

### Configure gsd-browser MCP Server

Source: https://opengsd.net/docs/v2/configuration

Add the gsd-browser server to your MCP configuration to enable browser automation capabilities.

```json
{
  "mcpServers": {
    "gsd-browser": {
      "type": "stdio",
      "command": "gsd-browser",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Enable Audit Trail via Environment Variable

Source: https://opengsd.net/docs/v1/configuration

Enable the append-only audit file by setting the GSD_AUDIT environment variable.

```bash
GSD_AUDIT=1 gsd plan
```

--------------------------------

### Configure PR Body Sections

Source: https://opengsd.net/docs/v1/configuration

Define custom PR body sections by adding entries to the ship.pr_body_sections array. At least one of source, template, or fallback must be provided for each section.

```json
{
  "ship": {
    "pr_body_sections": [
      {
        "heading": "User Stories & Acceptance Criteria",
        "enabled": true,
        "source": "REQUIREMENTS.md ## User Stories || REQUIREMENTS.md ## Acceptance Criteria",
        "fallback": "- Acceptance criteria are covered by the linked requirements and verification evidence."
      },
      {
        "heading": "Risks & Rollback",
        "enabled": true,
        "source": "PLAN.md ## Risks || PLAN.md ## Rollback",
        "fallback": "- Rollback: revert this PR."
      },
      {
        "heading": "Stakeholder Sign-off",
        "enabled": false,
        "template": "- Product owner: pending for {phase_name}"
      }
    ]
  }
}
```

--------------------------------

### Configure skill routing

Source: https://opengsd.net/docs/v2/configuration

Set preferences for which skills the agent should always use, prefer, or avoid.

```yaml
always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills: []
```