Skip to main content
GSD Pi includes a browser-based web interface that gives you a visual project dashboard alongside the terminal. Use it to monitor auto mode in real time, browse your knowledge base, edit preferences, manage multiple projects, and access a built-in terminal emulator — all from a standard web browser.

​
Launching the Web Interface

Start the web interface from your terminal with the --web flag: 
gsd --web
This starts a local web server and opens the GSD dashboard in your default browser. The URL (including port) is printed to the terminal on startup — typically http://localhost:3000. You can also pass an optional path to open GSD in a specific project directory: 
gsd --web /path/to/my-project

​
Starting and Stopping with the web Subcommand

Use the gsd web subcommand to manage the web server independently of a GSD session: 
gsd web          # Start the web server
gsd web stop     # Stop a running web server

​
Custom Host and Port

Override the default bind address and port with CLI flags: 
gsd --web --host 0.0.0.0 --port 8080
FlagDefaultDescription
--hostlocalhostBind address for the web server
--port3000Port for the web server
--allowed-origins(none)Comma-separated list of allowed CORS origins
Binding to 0.0.0.0 exposes the web UI on all network interfaces. Only do this on trusted networks or behind a firewall. The web server has no built-in authentication beyond the session token GSD generates at startup.

​
What the Web UI Provides

Terminal Emulator

A full xterm.js-powered terminal runs inside the browser. Start GSD sessions, run commands, and interact with the TUI without leaving the web interface.

Project Dashboard

A visual overview of milestones, slices, and tasks with progress indicators, dependency graphs, and status badges.

Live State Viewer

Server-sent events push real-time updates as auto mode executes. Watch tasks complete, costs accumulate, and milestone progress advance without refreshing the page.

Session Management

Switch between active sessions, view session history, and resume a previous session — all from the browser sidebar.

Knowledge Browser

Browse your project’s knowledge base including KNOWLEDGE.md rules, patterns, lessons, and architectural decisions stored in DECISIONS.md.

Preferences Editor

Edit global and project-level preferences through a guided web form — no need to manually edit YAML frontmatter in PREFERENCES.md.

File Browser

Navigate the project directory and .gsd/ artifact files directly from the browser, with syntax-highlighted viewing.

Cost Tracking

Live cost panels show per-session and per-milestone spending, token usage, and projections based on current burn rate.

​
Multi-Project Support

The web UI supports multiple projects from a single browser tab. Switch between projects using the ?project= URL parameter: 
http://localhost:3000?project=/path/to/other-project
You can also change the active project root from within the web UI without restarting the server. Set GSD_WEB_PROJECT_CWD as an environment variable to specify the default project when ?project= is not in the URL: 
GSD_WEB_PROJECT_CWD=/path/to/my-project gsd --web

​
Notification History

The web UI tracks all notifications GSD sends during a session — milestone completions, budget alerts, blockers, and attention requests — in a persistent notification panel. Click any notification to jump to the relevant part of the dashboard.

​
Platform Notes

The GSD Pi web interface is supported on macOS and Linux. The web build is skipped on Windows due to Next.js webpack compatibility issues with certain system directories. The GSD CLI and TUI remain fully functional on Windows.

​
MCP and API Routes

The web server exposes a rich set of API routes that power the dashboard. These routes are also available for integrations and tooling:
RouteDescription
/api/live-stateSSE stream of live session state
/api/projectsList and switch projects
/api/preferencesRead and write preferences
/api/knowledgeBrowse the knowledge base
/api/sessionSession management
/api/gitGit status and worktree info
/api/notificationsNotification history
/api/historyExecution history
/api/terminalTerminal bridge for xterm.js
You can use the /api/live-state SSE endpoint to build your own dashboard integrations — pipe the event stream to monitoring tools, Slack webhooks, or any system that can consume server-sent events.