docs(user-docs): rewrite getting-started guide with per-OS step-by-step instructions
Add comprehensive installation walkthroughs for macOS, Windows, Linux (Ubuntu/Debian, Fedora/RHEL, Arch, nvm), and Docker. Each OS section follows a consistent numbered step-by-step flow covering dependency install, verification, GSD install, provider setup, first launch, and verification. Includes download links, platform-specific tips, and a quick troubleshooting table.
This commit is contained in:
Jeremy
parent
452ad4fafe
commit
cefb70ba75
1 changed files with 371 additions and 98 deletions
|
|
@ -1,74 +1,311 @@
|
|||
# Getting Started
|
||||
# Getting Started with GSD
|
||||
|
||||
## Install
|
||||
GSD is an AI coding agent that handles planning, execution, verification, and shipping so you can focus on what to build. This guide walks you through installation on macOS, Windows, and Linux, then gets you running your first session.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Minimum | Recommended |
|
||||
|-------------|---------|-------------|
|
||||
| **[Node.js](https://nodejs.org/)** | 22.0.0 | 24 LTS |
|
||||
| **[Git](https://git-scm.com/)** | 2.20+ | Latest |
|
||||
| **LLM API key** | Any supported provider | Anthropic (Claude) |
|
||||
|
||||
Don't have Node.js or Git yet? Follow the OS-specific instructions below.
|
||||
|
||||
---
|
||||
|
||||
## Install by Operating System
|
||||
|
||||
### macOS
|
||||
|
||||
> **Downloads:** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/mac) | [Homebrew](https://brew.sh/)
|
||||
|
||||
**Step 1 — Install Homebrew** (skip if you already have it):
|
||||
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
**Step 2 — Install Node.js and Git:**
|
||||
|
||||
```bash
|
||||
brew install node git
|
||||
```
|
||||
|
||||
**Step 3 — Verify dependencies are installed:**
|
||||
|
||||
```bash
|
||||
node --version # should print v22.x or higher
|
||||
git --version # should print 2.20+
|
||||
```
|
||||
|
||||
**Step 4 — Install GSD:**
|
||||
|
||||
```bash
|
||||
npm install -g gsd-pi
|
||||
```
|
||||
|
||||
Requires Node.js ≥ 22.0.0 (24 LTS recommended) and Git.
|
||||
|
||||
> **`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [Troubleshooting](./troubleshooting.md#command-not-found-gsd-after-install) for details.
|
||||
|
||||
GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`.
|
||||
|
||||
### Set up API keys
|
||||
|
||||
If you use a non-Anthropic model, you'll need a search API key for web search. Run `/gsd config` to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects:
|
||||
**Step 5 — Set up your LLM provider:**
|
||||
|
||||
```bash
|
||||
# Inside any GSD session:
|
||||
/gsd config
|
||||
```
|
||||
# Option A: Set an environment variable (Anthropic recommended)
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
See [Global API Keys](./configuration.md#global-api-keys-gsd-config) for details on supported keys.
|
||||
|
||||
### Set up custom MCP servers
|
||||
|
||||
If you want GSD to call local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`.
|
||||
|
||||
See [Configuration → MCP Servers](./configuration.md#mcp-servers) for examples and verification steps.
|
||||
|
||||
### VS Code Extension
|
||||
|
||||
GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides:
|
||||
|
||||
- **`@gsd` chat participant** — talk to the agent in VS Code Chat
|
||||
- **Sidebar dashboard** — connection status, model info, token usage, quick actions
|
||||
- **Full command palette** — start/stop agent, switch models, export sessions
|
||||
|
||||
The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC.
|
||||
|
||||
### Web Interface
|
||||
|
||||
GSD also has a browser-based interface. Run `gsd --web` to start a local web server with a visual dashboard, real-time progress, and multi-project support. See [Web Interface](./web-interface.md) for details.
|
||||
|
||||
## First Launch
|
||||
|
||||
Run `gsd` in any directory:
|
||||
|
||||
```bash
|
||||
gsd
|
||||
```
|
||||
|
||||
GSD displays a welcome screen showing your version, active model, and available tool keys. Then on first launch, it runs a setup wizard:
|
||||
|
||||
1. **LLM Provider** — select from 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). Paste an API key, or use OAuth for supported providers like GitHub Copilot. Claude subscription users should authenticate through the local Claude Code CLI.
|
||||
2. **Tool API Keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any.
|
||||
|
||||
If you have an existing Pi installation, provider credentials are imported automatically.
|
||||
|
||||
For detailed setup instructions for specific providers (OpenRouter, Ollama, LM Studio, vLLM, and more), see the [Provider Setup Guide](./providers.md).
|
||||
|
||||
Re-run the wizard anytime with:
|
||||
|
||||
```bash
|
||||
# Option B: Use the built-in config wizard
|
||||
gsd config
|
||||
```
|
||||
|
||||
## Choose a Model
|
||||
To persist the key, add the export line to `~/.zshrc`:
|
||||
|
||||
GSD auto-selects a default model after login. Switch later with:
|
||||
```bash
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
|
||||
|
||||
**Step 6 — Launch GSD:**
|
||||
|
||||
```bash
|
||||
cd ~/my-project # navigate to any project
|
||||
gsd # start a session
|
||||
```
|
||||
|
||||
**Step 7 — Verify everything works:**
|
||||
|
||||
```bash
|
||||
gsd --version # prints the installed version
|
||||
```
|
||||
|
||||
Inside the session, type `/model` to confirm your LLM is connected.
|
||||
|
||||
> **Apple Silicon PATH fix:** If `gsd` isn't found after install, npm's global bin may not be in your PATH:
|
||||
> ```bash
|
||||
> echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
|
||||
> source ~/.zshrc
|
||||
> ```
|
||||
|
||||
> **oh-my-zsh conflict:** The oh-my-zsh git plugin defines `alias gsd='git svn dcommit'`. Fix with `unalias gsd 2>/dev/null` in `~/.zshrc`, or use `gsd-cli` instead.
|
||||
|
||||
---
|
||||
|
||||
### Windows
|
||||
|
||||
> **Downloads:** [Node.js](https://nodejs.org/) | [Git for Windows](https://git-scm.com/download/win) | [Windows Terminal](https://aka.ms/terminal)
|
||||
|
||||
#### Option A: winget (recommended for Windows 10/11)
|
||||
|
||||
**Step 1 — Install Node.js and Git:**
|
||||
|
||||
```powershell
|
||||
winget install OpenJS.NodeJS.LTS
|
||||
winget install Git.Git
|
||||
```
|
||||
|
||||
**Step 2 — Restart your terminal** (close and reopen PowerShell or Windows Terminal).
|
||||
|
||||
**Step 3 — Verify dependencies are installed:**
|
||||
|
||||
```powershell
|
||||
node --version # should print v22.x or higher
|
||||
git --version # should print 2.20+
|
||||
```
|
||||
|
||||
**Step 4 — Install GSD:**
|
||||
|
||||
```powershell
|
||||
npm install -g gsd-pi
|
||||
```
|
||||
|
||||
**Step 5 — Set up your LLM provider:**
|
||||
|
||||
```powershell
|
||||
# Option A: Set an environment variable (current session)
|
||||
$env:ANTHROPIC_API_KEY = "sk-ant-..."
|
||||
|
||||
# Option B: Use the built-in config wizard
|
||||
gsd config
|
||||
```
|
||||
|
||||
To persist the key permanently, add it via System Settings > Environment Variables, or run:
|
||||
|
||||
```powershell
|
||||
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")
|
||||
```
|
||||
|
||||
See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
|
||||
|
||||
**Step 6 — Launch GSD:**
|
||||
|
||||
```powershell
|
||||
cd C:\Users\you\my-project # navigate to any project
|
||||
gsd # start a session
|
||||
```
|
||||
|
||||
**Step 7 — Verify everything works:**
|
||||
|
||||
```powershell
|
||||
gsd --version # prints the installed version
|
||||
```
|
||||
|
||||
Inside the session, type `/model` to confirm your LLM is connected.
|
||||
|
||||
#### Option B: Manual install
|
||||
|
||||
1. Download and install [Node.js LTS](https://nodejs.org/) — check **"Add to PATH"** during setup
|
||||
2. Download and install [Git for Windows](https://git-scm.com/download/win) — use default options
|
||||
3. Open a **new** terminal, then follow Steps 3-7 above
|
||||
|
||||
> **Windows tips:**
|
||||
> - Use **Windows Terminal** or **PowerShell** for the best experience. Command Prompt works but has limited color support.
|
||||
> - If `gsd` isn't recognized, restart your terminal. Windows needs a fresh terminal to pick up new PATH entries.
|
||||
> - **WSL2** also works — install WSL, then follow the Linux instructions inside your distro.
|
||||
|
||||
---
|
||||
|
||||
### Linux
|
||||
|
||||
> **Downloads:** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/linux) | [nvm](https://github.com/nvm-sh/nvm)
|
||||
|
||||
Pick your distro, then follow the steps.
|
||||
|
||||
#### Ubuntu / Debian
|
||||
|
||||
**Step 1 — Install Node.js and Git:**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs git
|
||||
```
|
||||
|
||||
#### Fedora / RHEL / CentOS
|
||||
|
||||
**Step 1 — Install Node.js and Git:**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
|
||||
sudo dnf install -y nodejs git
|
||||
```
|
||||
|
||||
#### Arch Linux
|
||||
|
||||
**Step 1 — Install Node.js and Git:**
|
||||
|
||||
```bash
|
||||
sudo pacman -S nodejs npm git
|
||||
```
|
||||
|
||||
#### Using nvm (any distro)
|
||||
|
||||
**Step 1 — Install nvm, then Node.js:**
|
||||
|
||||
```bash
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
|
||||
source ~/.bashrc # or ~/.zshrc
|
||||
nvm install 24
|
||||
nvm use 24
|
||||
```
|
||||
|
||||
#### All distros: Steps 2-7
|
||||
|
||||
**Step 2 — Verify dependencies are installed:**
|
||||
|
||||
```bash
|
||||
node --version # should print v22.x or higher
|
||||
git --version # should print 2.20+
|
||||
```
|
||||
|
||||
**Step 3 — Install GSD:**
|
||||
|
||||
```bash
|
||||
npm install -g gsd-pi
|
||||
```
|
||||
|
||||
**Step 4 — Set up your LLM provider:**
|
||||
|
||||
```bash
|
||||
# Option A: Set an environment variable (Anthropic recommended)
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
# Option B: Use the built-in config wizard
|
||||
gsd config
|
||||
```
|
||||
|
||||
To persist the key, add the export line to `~/.bashrc` (or `~/.zshrc`):
|
||||
|
||||
```bash
|
||||
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
See [Provider Setup Guide](./providers.md) for all 20+ supported providers.
|
||||
|
||||
**Step 5 — Launch GSD:**
|
||||
|
||||
```bash
|
||||
cd ~/my-project # navigate to any project
|
||||
gsd # start a session
|
||||
```
|
||||
|
||||
**Step 6 — Verify everything works:**
|
||||
|
||||
```bash
|
||||
gsd --version # prints the installed version
|
||||
```
|
||||
|
||||
Inside the session, type `/model` to confirm your LLM is connected.
|
||||
|
||||
> **Permission errors on `npm install -g`?** Don't use `sudo npm`. Fix npm's global directory instead:
|
||||
> ```bash
|
||||
> mkdir -p ~/.npm-global
|
||||
> npm config set prefix '~/.npm-global'
|
||||
> echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
|
||||
> source ~/.bashrc
|
||||
> npm install -g gsd-pi
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
### Docker (any OS)
|
||||
|
||||
> **Downloads:** [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||||
|
||||
Run GSD in an isolated sandbox without installing Node.js on your host.
|
||||
|
||||
**Step 1 — Install Docker Desktop** (4.58+ required).
|
||||
|
||||
**Step 2 — Clone the GSD repo:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/gsd-build/gsd-2.git
|
||||
cd gsd-2/docker
|
||||
```
|
||||
|
||||
**Step 3 — Create and enter a sandbox:**
|
||||
|
||||
```bash
|
||||
docker sandbox create --template . --name gsd-sandbox
|
||||
docker sandbox exec -it gsd-sandbox bash
|
||||
```
|
||||
|
||||
**Step 4 — Set your API key and run GSD:**
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
gsd auto "implement the feature described in issue #42"
|
||||
```
|
||||
|
||||
See [Docker Sandbox docs](../../docker/README.md) for full configuration, resource limits, and compose files.
|
||||
|
||||
---
|
||||
|
||||
## After Installation
|
||||
|
||||
### Choose a Model
|
||||
|
||||
GSD auto-selects a default model after provider setup. Switch anytime inside a session:
|
||||
|
||||
```
|
||||
/model
|
||||
|
|
@ -76,18 +313,20 @@ GSD auto-selects a default model after login. Switch later with:
|
|||
|
||||
Or configure per-phase models in preferences — see [Configuration](./configuration.md).
|
||||
|
||||
---
|
||||
|
||||
## Two Ways to Work
|
||||
|
||||
### Step Mode — `/gsd`
|
||||
|
||||
Type `/gsd` inside a session. GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next.
|
||||
|
||||
- **No `.gsd/` directory** → starts a discussion flow to capture your project vision
|
||||
- **Milestone exists, no roadmap** → discuss or research the milestone
|
||||
- **Roadmap exists, slices pending** → plan the next slice or execute a task
|
||||
- **Mid-task** → resume where you left off
|
||||
- **No `.gsd/` directory** — starts a discussion flow to capture your project vision
|
||||
- **Milestone exists, no roadmap** — discuss or research the milestone
|
||||
- **Roadmap exists, slices pending** — plan the next slice or execute a task
|
||||
- **Mid-task** — resume where you left off
|
||||
|
||||
Step mode is the on-ramp. You stay in the loop, reviewing output between each step.
|
||||
Step mode keeps you in the loop, reviewing output between each step.
|
||||
|
||||
### Auto Mode — `/gsd auto`
|
||||
|
||||
|
|
@ -99,9 +338,11 @@ Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, ve
|
|||
|
||||
See [Auto Mode](./auto-mode.md) for full details.
|
||||
|
||||
## Two Terminals, One Project
|
||||
---
|
||||
|
||||
The recommended workflow: auto mode in one terminal, steering from another.
|
||||
## Recommended Workflow: Two Terminals
|
||||
|
||||
Run auto mode in one terminal, steer from another.
|
||||
|
||||
**Terminal 1 — let it build:**
|
||||
|
||||
|
|
@ -121,9 +362,9 @@ gsd
|
|||
|
||||
Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically.
|
||||
|
||||
## Project Structure
|
||||
---
|
||||
|
||||
GSD organizes work into a hierarchy:
|
||||
## How GSD Organizes Work
|
||||
|
||||
```
|
||||
Milestone → a shippable version (4-10 slices)
|
||||
|
|
@ -138,25 +379,45 @@ All state lives on disk in `.gsd/`:
|
|||
```
|
||||
.gsd/
|
||||
PROJECT.md — what the project is right now
|
||||
REQUIREMENTS.md — requirement contract (active/validated/deferred)
|
||||
REQUIREMENTS.md — requirement contract
|
||||
DECISIONS.md — append-only architectural decisions
|
||||
KNOWLEDGE.md — cross-session rules, patterns, and lessons
|
||||
RUNTIME.md — runtime context: API endpoints, env vars, services (v2.39)
|
||||
KNOWLEDGE.md — cross-session rules and patterns
|
||||
STATE.md — quick-glance status
|
||||
milestones/
|
||||
M001/
|
||||
M001-ROADMAP.md — slice plan with risk levels and dependencies
|
||||
M001-CONTEXT.md — scope and goals from discussion
|
||||
M001-ROADMAP.md — slice plan with dependencies
|
||||
slices/
|
||||
S01/
|
||||
S01-PLAN.md — task decomposition
|
||||
S01-SUMMARY.md — what happened
|
||||
S01-UAT.md — human test script
|
||||
tasks/
|
||||
T01-PLAN.md
|
||||
T01-SUMMARY.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VS Code Extension
|
||||
|
||||
GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions:
|
||||
|
||||
- **`@gsd` chat participant** — talk to the agent in VS Code Chat
|
||||
- **Sidebar dashboard** — connection status, model info, token usage
|
||||
- **Full command palette** — start/stop agent, switch models, export sessions
|
||||
|
||||
The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC.
|
||||
|
||||
---
|
||||
|
||||
## Web Interface
|
||||
|
||||
GSD has a browser-based interface for visual project management:
|
||||
|
||||
```bash
|
||||
gsd --web
|
||||
```
|
||||
|
||||
See [Web Interface](./web-interface.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## Resume a Session
|
||||
|
||||
```bash
|
||||
|
|
@ -165,36 +426,48 @@ gsd --continue # or gsd -c
|
|||
|
||||
Resumes the most recent session for the current directory.
|
||||
|
||||
To browse and pick from all saved sessions:
|
||||
Browse all saved sessions:
|
||||
|
||||
```bash
|
||||
gsd sessions
|
||||
```
|
||||
|
||||
Shows each session's date, message count, and first-message preview so you can choose which one to resume.
|
||||
---
|
||||
|
||||
## Updating GSD
|
||||
|
||||
GSD checks for updates every 24 hours and prompts at startup. You can also update manually:
|
||||
|
||||
```bash
|
||||
npm update -g gsd-pi
|
||||
```
|
||||
|
||||
Or from within a session:
|
||||
|
||||
```
|
||||
/gsd update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
| Problem | Fix |
|
||||
|---------|-----|
|
||||
| `command not found: gsd` | Add npm global bin to PATH (see OS-specific notes above) |
|
||||
| `gsd` runs `git svn dcommit` | oh-my-zsh conflict — `unalias gsd` or use `gsd-cli` |
|
||||
| Permission errors on `npm install -g` | Fix npm prefix (see Linux notes) or use nvm |
|
||||
| Can't connect to LLM | Check API key with `gsd config`, verify network access |
|
||||
| `gsd` hangs on start | Check Node.js version: `node --version` (need 22+) |
|
||||
|
||||
For more, see [Troubleshooting](./troubleshooting.md).
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Auto Mode](./auto-mode.md) — deep dive into autonomous execution
|
||||
- [Configuration](./configuration.md) — model selection, timeouts, budgets
|
||||
- [Commands Reference](./commands.md) — all commands and shortcuts
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `gsd` command runs `git svn dcommit` instead of GSD
|
||||
|
||||
The [oh-my-zsh git plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git) defines `alias gsd='git svn dcommit'`, which shadows the GSD binary.
|
||||
|
||||
**Option 1** — Remove the alias in your `~/.zshrc` (add after the `source $ZSH/oh-my-zsh.sh` line):
|
||||
|
||||
```bash
|
||||
unalias gsd 2>/dev/null
|
||||
```
|
||||
|
||||
**Option 2** — Use the alternative binary name:
|
||||
|
||||
```bash
|
||||
gsd-cli
|
||||
```
|
||||
|
||||
Both `gsd` and `gsd-cli` point to the same binary.
|
||||
- [Provider Setup](./providers.md) — detailed setup for every provider
|
||||
- [Working in Teams](./working-in-teams.md) — multi-developer workflows
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue