Gas Town GUI

A standalone web GUI for Gas Town - the multi-agent orchestration system for Claude Code.

Note: This is an independent companion project, not part of the official Gas Town repository. Originally submitted as PR #212, now maintained as a standalone package per Steve's recommendation.

"Thank you for the impressive work on this GUI! The effort and thought that went into it is clear - the architecture is clean, the documentation is thorough, and it demonstrates a solid understanding of Gas Town's workflow. [...] If you're interested in continuing this work, I'd encourage publishing it as a standalone companion project."

— Steve Yegge, creator of Gas Town (PR #212 comment)

Status: 🚧 Candidate for Testing - Provides a solid starting point for a Gas Town GUI interface.

Quick Start

1. Install Prerequisites

# Gas Town CLI (required)
npm install -g @gastown/gt
# Or: go install github.com/steveyegge/gastown/cmd/gt@latest

# GitHub CLI (optional, for PR tracking)
gh auth login

2. Install Gas Town GUI

# Via npm (recommended)
npm install -g gastown-gui

# Or from source
git clone https://github.com/web3dev1337/gastown-gui.git
cd gastown-gui
npm install
npm link

3. Start the GUI

gastown-gui start --open

Opens http://localhost:7667 in your browser.

4. Verify Setup

gastown-gui doctor

Features

• Rig Management - Add, view, and organize project repositories
• Work Tracking - Create and manage work items (beads)
• Task Assignment - Sling work to rigs and agents
• Real-Time Updates - Live WebSocket updates for all operations
• PR Tracking - View GitHub pull requests across projects
• Mail Inbox - Read messages from agents and polecats
• Health Monitoring - Run doctor checks and view system status

CLI Usage

# Start server (default port 7667)
gastown-gui

# Custom port
gastown-gui start --port 4000

# Open browser automatically
gastown-gui start --open

# Development mode
gastown-gui start --dev

# Check prerequisites
gastown-gui doctor

# Show version
gastown-gui version

# Show help
gastown-gui help

Options

| Option | Description | Default | |--------|-------------|---------| | --port, -p | Server port | 7667 | | --host, -h | Server host | 127.0.0.1 | | --open, -o | Open browser | false | | --dev | Development mode | false |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GASTOWN_PORT | Server port | 7667 | | HOST | Server host | 127.0.0.1 | | GT_ROOT | Gas Town root directory | ~/gt |

How It Works

The GUI acts as a bridge between your browser and the Gas Town CLI:

┌─────────────┐
│   Browser   │
│   (Client)  │
└──────┬──────┘
       │ HTTP API / WebSocket
       ↓
┌─────────────┐
│  gastown-   │
│  gui server │
└──────┬──────┘
       │ subprocess (gt, bd, gh)
       ↓
┌─────────────┐
│   ~/gt/     │
│  workspace  │
└─────────────┘

All operations execute through the official gt and bd commands - the GUI never directly modifies Gas Town's internal state.

Architecture

Tech Stack

• Backend: Node.js + Express
• Frontend: Vanilla JavaScript (no framework)
• Communication: WebSocket for real-time updates
• Testing: Vitest + Puppeteer E2E tests

Design Principles

1. Server-Authoritative - All operations execute via gt and bd CLI commands
2. Non-Blocking UI - Modals close immediately, operations run in background
3. Real-Time Updates - WebSocket broadcasts status changes to all clients
4. Graceful Degradation - UI handles missing data and command failures
5. Cache & Refresh - Background data preloading with stale-while-revalidate

API Endpoints

| Method | Endpoint | Description | CLI Command | |--------|----------|-------------|-------------| | GET | /api/status | System status | gt status --json | | GET | /api/rigs | List rigs | gt rig list | | POST | /api/rigs | Add rig | gt rig add | | GET | /api/work | List work items | bd list | | POST | /api/work | Create work | bd new | | POST | /api/sling | Sling work | gt sling | | GET | /api/prs | GitHub PRs | gh pr list | | GET | /api/mail | Mail inbox | gt mail inbox | | GET | /api/doctor | Health check | gt doctor |

Project Structure

gastown-gui/
├── bin/cli.js           # CLI entry point
├── server.js            # Express + WebSocket server
├── index.html           # Main HTML (single page)
├── css/                 # Stylesheets
│   ├── variables.css
│   ├── reset.css
│   ├── layout.css
│   ├── components.css
│   └── animations.css
├── js/
│   ├── app.js           # Main app entry
│   ├── api.js           # API client
│   ├── state.js         # State management
│   └── components/      # UI components
│       ├── dashboard.js
│       ├── rig-list.js
│       ├── work-list.js
│       ├── pr-list.js
│       ├── mail-list.js
│       └── ...
├── test/
│   ├── unit/            # Unit tests
│   └── e2e.test.js      # E2E tests
└── assets/              # Favicons, icons

Testing

# All tests
npm test

# Unit tests only
npm run test:unit

# E2E tests
npm run test:e2e

# Watch mode
npm run test:watch

Known Limitations

Remaining Features (Use CLI)

| Feature | Status | |---------|--------| | Agent configuration UI | ❌ Not implemented |

Implemented Features

| Feature | Status | |---------|--------| | Polecat spawn/stop/restart | ✅ UI in Rig list | | Rig deletion | ✅ Remove button in Rig list | | Crew management | ✅ Create/list/view | | Formula operations | ✅ Create/list/use | | Test coverage | ✅ 206 tests passing |

Known Issues:

• GT CLI sling may fail with "mol bond requires direct database access" (upstream issue)

Compatibility

• Gas Town: v0.2.x and later
• Node.js: 18, 20, 22
• Browsers: Chrome, Firefox, Safari (latest)

The GUI calls CLI commands via subprocess, so it should work with any Gas Town version that has compatible CLI output.

Contributing

Contributions welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Update CLAUDE.md if you add, rename, or delete files
5. Test locally (start server with npm start, verify in browser)
6. Run automated tests: npm test (206 tests must pass)
7. Submit a pull request

Looking for Maintainers

We're looking for maintainers to help review and merge PRs. If you're interested in helping maintain this project, please open an issue or reach out!

License

MIT

Credits

• Gas Town: steveyegge/gastown by Steve Yegge
• GUI Implementation: Built with Claude Code
• Original PR: #212

Contributors

Thanks to these community members who contributed to the original PR through testing, comments, and recommended fixes:

• @gsxdsm
• @michaellady
• @olivierlefloch
• @zalo
• @irelandpaul

Disclaimer: This is an independent community project, not officially affiliated with Gas Town. Use at your own risk.