Superposition

Superposition is a web-based application designed for executing AI coding sessions using Claude Code and Codex, tailored for GitHub repositories. Each coding session is conducted in an isolated Git worktree, providing a secure environment for development alongside a comprehensive browser-based terminal.

Key Features

• Multi-CLI Support: Choose between Claude Code and Codex for your coding sessions.
• Branch Isolation: Every session operates in its unique Git worktree to avoid interference between parallel sessions.
• Browser Terminal: Utilizes a full xterm.js terminal equipped with reconnection capabilities and a replay buffer.
• Repository Management: Effortlessly clone and sync GitHub repositories through a Personal Access Token.
• Single Binary: Compiles into a standalone Go binary, integrating the React frontend seamlessly.

User Interface

Sessions Overview

Easily view and manage all active sessions, with details such as repository, branch, CLI type, and session ID presented in a user-friendly card format.

Creating New Sessions

Intuitively create new sessions by selecting the repository, source branch, and new branch name, along with the desired CLI.

Terminal Interaction

Engage directly with Claude Code or Codex in the browser, enabling an interactive coding experience.

Repository Management

Add and sync GitHub repositories to maintain up-to-date branches effortlessly.

Configuration Settings

Configure personal access tokens for GitHub repository access directly within the application settings.

Architecture

Superposition is structured with a straightforward 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

The backend is built with Go, utilizing standard libraries for routing, SQLite for data management, and WebSocket for terminal streaming. The frontend leverages React for a responsive user interface.

Quick Start Example

To get started with Superposition, users can build the application with the following commands:

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

# Build the binary
make build

# Run the application
./superposition

Access the application at http://127.0.0.1:8800 in a web browser.