Superposition

A web-based application for running AI coding sessions (Claude Code and Codex) against your GitHub repositories. Each session runs in an isolated git worktree with a full browser-based terminal.

Features

• Multi-CLI Support — Run sessions with Claude Code or Codex
• Branch Isolation — Each session gets its own git worktree, so parallel sessions never conflict
• Browser Terminal — Full xterm.js terminal with reconnection support and replay buffer
• Repository Management — Clone and sync GitHub repos via Personal Access Token
• Single Binary — Compiles to a standalone Go binary with the React frontend embedded

Screenshots

Sessions

View and manage all running sessions. Each card shows the repo, branch, CLI type, and session ID.

New Session

Create a session by picking a repo, source branch, new branch name, and CLI.

Terminal

Interact with Claude Code or Codex directly in the browser.

Repositories

Add GitHub repos and sync them to keep branches up to date.

Settings

Configure your GitHub Personal Access Token for repo access.

Prerequisites

• Git — required
• Go 1.23+ — for building from source
• Node.js / npm — for building the frontend
• Claude Code and/or Codex CLI installed on your PATH

Quick Start

# Clone the repo
git clone https://github.com/trezm/superposition.git
cd superposition

# Build the binary (compiles frontend + Go backend)
make build

# Run it
./superposition

Open http://127.0.0.1:8800 in your browser.

First-time setup

1. Go to Settings and enter your GitHub Personal Access Token (classic token with repo scope)
2. Go to Repositories and add a repo from the list
3. Go to Sessions, click New Session, pick your repo and branch, and start coding

Development

Run the backend and frontend separately for hot-reload:

# Terminal 1 — Go backend on :8800
make dev-backend

# Terminal 2 — Vite dev server on :5173 (proxies API to :8800)
make dev-frontend

Production Build

make build

This produces a single ./superposition binary with the React SPA embedded. No external files needed.

CLI flags

-port int   server port (default 8800)

Architecture

├── main.go                  # Entry point, server bootstrap
├── migrations/              # SQLite schema
├── internal/
│   ├── api/                 # REST handlers (repos, sessions, settings)
│   ├── db/                  # Database helpers
│   ├── git/                 # Git operations (clone, worktree, fetch)
│   ├── github/              # GitHub API client
│   ├── models/              # Data models
│   ├── pty/                 # PTY process management
│   ├── preflight/           # CLI dependency checks
│   ├── server/              # HTTP server + middleware
│   └── ws/                  # WebSocket terminal streaming
└── web/                     # React frontend
    └── src/
        ├── components/      # Terminal, Layout, Modal, Toast
        └── pages/           # Dashboard, Repos, Sessions, Settings

Backend: Go with standard library routing (Go 1.22+), SQLite, gorilla/websocket, creack/pty

Frontend: React 19, React Router 7, xterm.js, Tailwind CSS, Vite

Data: Stored in ~/.superposition/ — SQLite database, bare repo clones, and session worktrees

License

MIT