gsd-wmux

Multi-backend multiplexer integration for GSD / pi

Drop-in replacement for the stock @gsd/cmux library that adds WezTerm support and makes it trivial to add new backends (tmux, zellij, psmux, etc.).

GSD's auto-mode can publish status, progress, and notifications to your terminal multiplexer. The stock integration only supports cmux (macOS-only). This package adds:

# Install globally
npm install -g gsd-wmux

# Apply to your GSD installation
npx gsd-wmux

# Enable in your project
# (inside pi, run:)
/gsd cmux on

Copy the Lua snippet into your WezTerm config to see GSD status in the tab bar:

-- In your ~/.wezterm.lua, add:
local gsd = require('gsd-status')

Or copy wezterm/gsd-status.lua to your WezTerm config directory.

The status bar shows:

• 🚀 Phase icon (executing, planning, blocked, complete, etc.)
• Current milestone/slice/task label
• Progress bar with completion ratio
• Phase-colored highlights

gsd-wmux replaces the cmux integration library at ~/.gsd/agent/extensions/cmux/. Since GSD imports this library by relative path, the replacement is transparent — all existing GSD code works unchanged.

Backend auto-detection:

1. If WEZTERM_PANE is set → WezTerm backend
2. If CMUX_WORKSPACE_ID + CMUX_SURFACE_ID are set → cmux backend
3. If wezterm cli is on PATH → WezTerm backend
4. Otherwise → no backend (graceful no-op)

WezTerm status delivery:

• Status/progress data is pushed via OSC 1337 user variables (zero-latency, no polling)
• The companion Lua config reads pane.user_vars.gsd_* and renders them in the tab bar
• Desktop notifications use WezTerm's native OSC 777 support

gsd-wmux sets these user variables on the active pane. Your WezTerm Lua config can read them via pane:get_user_vars():

1. Implement MuxBackend (see src/types.ts) in src/backends/your-backend.ts
2. Add it to the BACKENDS array in src/index.ts
3. The auto-detection loop picks it up if detect() returns available: true

Example skeleton:

import type { MuxBackend, MuxConfig, MuxEnvironment } from "../types.js";

export class MyMuxBackend implements MuxBackend {
    readonly name = "mymux";

    detect(env = process.env): MuxEnvironment {
        // Check env vars, CLI availability, etc.
    }

    isCliAvailable(): boolean { /* ... */ }
    setStatus(config, label, phase) { /* ... */ }
    clearStatus(config) { /* ... */ }
    // ... implement remaining MuxBackend methods
}

# Check current state
npx gsd-wmux --status

# Revert to stock cmux
npx gsd-wmux --restore

# Re-apply after a pi update
npx gsd-wmux

After updating pi (npm update -g gsd-pi), the stock cmux files are restored. Run npx gsd-wmux again to re-apply.

gsd-wmux also patches GSD's notifications.js to add Windows toast notification support. The stock version returns null on win32 — the patched version uses PowerShell + WinRT to show native Windows 10/11 toast notifications.

git clone https://github.com/your-username/gsd-wmux.git
cd gsd-wmux
npm install
npm run build
node scripts/install.js

See CONTRIBUTING.md for a full development guide.

MIT