Open GSD

https://opengsd.net/docs
Admin
Open GSD is an AI agent orchestration framework and tool suite for planning, autonomous coding...
Tokens:37,211
Snippets:594
Trust Score:5.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 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"
}
```

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

### 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"
}
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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"
    }
  }
}
```

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

### 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 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
```

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

### 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"
  }
}
```

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

### 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
```

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

### Upgrade GSD

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

Updates the GSD installation to the latest release.

```bash
gsd upgrade
```

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

### 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
```

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

### 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.
```

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

### 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_..."
```

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

### 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
```

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

### 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
```

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

### 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 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 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
```

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

### 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
```

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

### 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"
```

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

### 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
```

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

### 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
```
Tokens:
Raw