logo1
GSD Skill Creator
GSD-OS Desktop

Documentation > Specialized Systems > GSD-OS Desktop Application

Guide IDSS-6
AudienceDevelopers, Power users
PrerequisitesGS-1: Installation, A-1: Chipset Architecture
Time20 minutes
DifficultyAdvanced

GSD-OS Desktop Application

GSD-OS is a Tauri-based desktop application that wraps gsd-skill-creator's CLI workflows in an Amiga-inspired graphical shell. It is not a web app deployed in a browser -- it is a native application with a Rust backend managing PTY sessions, file watching, tmux binding, and Claude session management, paired with a Vite-built TypeScript frontend that renders through a WebGL2 CRT shader engine with retro-computing aesthetics. The result is a desktop environment where terminal sessions, planning dashboards, and Claude interactions coexist as managed windows with Amiga-style chrome.

Two-Layer Architecture

GSD-OS is built on two technology layers connected through Tauri's IPC system:

Rust Backend (src-tauri/)

The Rust backend (src-tauri/) provides native system access that web technologies cannot offer. It is built with Tauri 2.10 and exposes functionality through IPC commands that the frontend invokes:

  • PTY management (src/pty/) -- Opens native pseudo-terminal sessions using the portable-pty crate. Manages session lifecycle (open, write, resize, pause, resume, close) and streams output to the frontend via Tauri's event system. Flow control prevents buffer overflows when the frontend cannot render output fast enough.
  • File watcher (src/watcher.rs) -- Monitors the .planning/ directory for changes using the notify crate with debounced events. When planning documents change (STATE.md updated, phase plan created), the watcher emits events that trigger dashboard refresh in the frontend.
  • tmux integration (src/tmux/) -- Detects tmux availability, lists existing sessions, and creates new sessions for GSD workflows. The tmux session binding allows GSD-OS to attach to a persistent tmux session, so terminal state survives application restarts.
  • Claude session management (src/claude/) -- Starts, stops, and monitors Claude Code sessions. The session manager tracks active sessions, their status, and resource consumption. The monitor provides health checks and lifecycle events.
  • Dashboard generation (src/commands/dashboard.rs) -- Generates planning dashboard HTML from the .planning/ directory structure, rendering roadmap progress, phase status, and session metrics.

The backend manages application state through thread-safe Mutex-wrapped state objects for the app, file watcher, PTY manager, and Claude session manager. The Tauri configuration (tauri.conf.json) defines a single decorationless main window at 1280x800 -- GSD-OS provides its own window chrome through the frontend's window manager.

Vite Frontend (desktop/)

The frontend (desktop/) is a TypeScript application built with Vite, producing a static bundle that Tauri serves as the application's web view. Key dependencies include @tauri-apps/api for IPC, @xterm/xterm with WebGL addon for terminal rendering, culori for OKLCH color space calculations, and zod for runtime type validation.

The frontend is organized into functional modules:

  • Engine (desktop/src/engine/) -- The WebGL2 rendering pipeline including CRT shader effects, copper list processing, palette texture generation, render targets, and performance monitoring.
  • Window Manager (desktop/src/wm/) -- Amiga-style window management with depth cycling, drag/resize, and z-order tracking.
  • Shell (desktop/src/shell/) -- Desktop shell with taskbar, system menu, desktop icons, icon registry, keyboard navigation, and process monitoring.
  • Boot (desktop/src/boot/) -- Startup animation sequence with chipset initialization and desktop background rendering.
  • Terminal (desktop/src/terminal/) -- xterm.js integration with PTY bridge, flow control, and WebGL-accelerated rendering.
  • tmux (desktop/src/tmux/) -- tmux session UI with bridge to the Rust backend's tmux detection and session management.
  • Claude (desktop/src/claude/) -- Claude session UI with bridge to the backend's session manager and a monitor that tracks session health.
  • Dashboard (desktop/src/dashboard/) -- Planning dashboard host that renders .planning/ data within GSD-OS windows, with palette-aware styling and live refresh from the file watcher.
  • Calibration (desktop/src/calibration/) -- Three-screen setup wizard for theme mode, CRT settings, and color picker customization.
  • IPC (desktop/src/ipc/) -- Command invocation, event listening, channel-based streaming, file watcher binding, and IPC benchmarking.

CRT Shader Engine

The visual identity of GSD-OS comes from its WebGL2 CRT shader pipeline (desktop/src/engine/). The engine renders all frontend content through a multi-pass shader chain that simulates a CRT monitor:

  • CRT distortion pass (shaders/crt-distort.frag) -- Applies barrel distortion and vignetting to simulate CRT screen curvature.
  • CRT post-processing pass (shaders/crt-post.frag) -- Adds scanlines, phosphor glow, and color fringing for authentic CRT appearance.
  • Palette background pass (shaders/palette-bg.frag) -- Renders the desktop background using palette-indexed colors driven by the copper list.

CRT intensity, scanline density, and color effects are configurable through the calibration wizard. Users who prefer a clean display can reduce or disable CRT effects entirely while retaining the Amiga-style UI.

Fox Palette and Copper Lists

GSD-OS uses a 32-color palette system (desktop/src/engine/palette.ts) with five built-in presets: Amiga Workbench 1.3 (blue/white/black/orange core), Amiga Workbench 2.0 (gray-based with colored accents), Amiga Workbench 3.1 MagicWB (full 32-color UI chrome), Commodore 64 (canonical 16 colors with 16 variations), and a custom default. Users can generate custom palettes from anchor colors using OKLCH color space calculations that produce harmonious 32-color sets with controlled lightness, chroma, and hue distribution.

Copper lists (desktop/src/engine/copper-list.ts) are inspired by the Amiga's copper coprocessor, which could change display parameters on each scanline. In GSD-OS, a copper list is a program that specifies per-scanline background colors by referencing palette indices with interpolation. Each entry defines a scanline range, two palette indices, and a blend factor. The copper list is encoded as an Nx1 RGBA texture and uploaded to the GPU, where the palette background shader reads it to produce gradient backgrounds and raster bar effects -- all at GPU speed with zero CPU overhead per frame.

Three built-in copper programs are provided: "gradient" (smooth vertical blend across all 256 virtual scanlines), "raster-bars" (colored horizontal bands on a black background), and "flat" (single solid color).

Window Manager

The window manager (desktop/src/wm/) implements Amiga-style window management with several distinctive features:

  • Depth cycling -- The signature Amiga interaction model. Clicking a window's depth gadget sends it to the back of the z-order stack, cycling through windows without a traditional alt-tab mechanism. Each depth cycle emits a depth-cycled event.
  • Window chrome (window-chrome.ts) -- Each window has Amiga-style title bar with close, minimize (iconify), and depth gadgets. The chrome is rendered by the frontend, not the native OS -- hence the decorationless Tauri window.
  • Drag and resize (drag-resize.ts) -- Windows can be moved by dragging the title bar and resized by dragging window edges. Minimum size constraints prevent windows from being resized to unusable dimensions.
  • Z-order management (z-order.ts) -- Maintains a strict front-to-back ordering of all windows. Clicking a window brings it to front. The depth cycling gadget sends it to back. The system ensures exactly one window has focus at any time.
  • Minimize to icon -- Minimized windows appear as desktop icons in the icon container, mirroring the Amiga Workbench's iconify behavior.

Boot Sequence

GSD-OS starts with an Amiga-inspired boot animation (desktop/src/boot/). The sequence progresses through four phases: init (blank screen, 400ms), chipset initialization (four custom chipsets initialize in order: Agnus/Graphics DMA at 600ms, Denise/Display Encoder at 800ms, Paula/Audio and I/O at 700ms, Gary/Address Decode at 500ms), ready (system ready display, 800ms), and complete (fade to desktop). Total boot time is under 5 seconds.

The boot state machine (chipset.ts) is a pure function that advances based on elapsed time -- no timers, no DOM, no side effects. The boot renderer reads the state and produces the visual output. Users can skip the boot animation by pressing any key or clicking, and the skip preference can be persisted in user configuration.

After boot completes, a three-screen calibration wizard guides first-time users through theme mode selection (dark/light/auto), CRT shader intensity settings, and color palette customization.

Terminal Integration

Terminal windows in GSD-OS use xterm.js (desktop/src/terminal/) connected to native PTY sessions through the Rust backend. The terminal emulator (terminal-emulator.ts) creates an xterm.js instance with WebGL rendering, loads the fit addon for automatic sizing, and opens a PTY session through the IPC bridge. User keystrokes are forwarded to the PTY; PTY output is streamed through a flow controller that applies backpressure when the terminal cannot render fast enough, automatically pausing and resuming PTY reads.

tmux integration (desktop/src/tmux/) binds terminal windows to tmux sessions, providing session persistence across application restarts. When GSD-OS reconnects, it reattaches to existing tmux sessions rather than creating new ones, preserving terminal history and running processes.

Dashboard Integration

The dashboard host (desktop/src/dashboard/) renders the .planning/ directory's project state as a visual dashboard within GSD-OS windows. The dashboard bridge connects to the Rust backend's file watcher, receiving events when planning documents change. A palette bridge applies the current Fox palette theme to dashboard elements. Live refresh means the dashboard always reflects the current project state -- when a phase completes or STATE.md is updated, the dashboard window updates automatically without manual refresh.

What's Next