@lrilai/webterm

WebTerm - Web Terminal Multiplexer

A web-based terminal multiplexer inspired by tmux. Run multiple terminal sessions in your browser with split panes, session persistence, and AI CLI tool support.

Features

• 🖥️ Multi-pane terminal - Split horizontally/vertically, resize by dragging
• ⌨️ tmux-like keybindings - Familiar Ctrl+B prefix shortcuts
• 🎨 Cyberpunk theme - Beautiful terminal aesthetic with GlitchCN/UI
• 💾 Session persistence - Save and restore your terminal layouts
• 📡 Real-time communication - WebSocket with binary protocol for low latency
• 🤖 AI CLI support - Optimized for Claude Code, Gemini CLI, Codex
• 🔄 Broadcast mode - Type in multiple panes simultaneously

Quick Start

Prerequisites

• Node.js 20+ (LTS recommended)
• npm 10+ or pnpm
• Windows 10+, macOS, or Linux

Installation

# Clone the repository
git clone https://github.com/yourusername/webterm.git
cd webterm

# Install dependencies
npm install

# Build shared types
npm run build:shared

# Start development servers
npm run dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000
• WebSocket: ws://localhost:3000/ws

Production Build

# Build all packages
npm run build

# Start backend server
cd backend && npm start

Keybindings

All keybindings use the Ctrl+B prefix (press Ctrl+B, release, then press the command key):

Keybinding	Action
Ctrl+B %	Split pane vertically
Ctrl+B "	Split pane horizontally
Ctrl+B ←↑↓→	Navigate between panes
Ctrl+B x	Close current pane
Ctrl+B z	Zoom/unzoom pane
Ctrl+B c	Create new window
Ctrl+B n	Next window
Ctrl+B p	Previous window
Ctrl+B S	Save session
Ctrl+B ?	Show keybindings help

Copy/paste shortcuts (no prefix needed):

• Ctrl+Shift+C - Copy selected text
• Ctrl+Shift+V - Paste from clipboard

Project Structure

webterm/
├── backend/               # Node.js backend
│   └── src/
│       ├── api/           # WebSocket & REST handlers
│       ├── db/            # SQLite database
│       ├── models/        # Data models
│       ├── services/      # Business logic
│       └── utils/         # Utilities
├── frontend/              # React frontend
│   └── src/
│       ├── components/    # React components
│       ├── hooks/         # Custom hooks
│       ├── services/      # API clients
│       ├── stores/        # Zustand stores
│       └── styles/        # CSS & Tailwind
├── shared/                # Shared TypeScript types
│   └── types/
└── specs/                 # Feature specifications

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite, Tailwind CSS
Terminal	xterm.js with WebGL renderer
Backend	Node.js, TypeScript
PTY	node-pty (powers VS Code terminal)
Database	SQLite (better-sqlite3)
WebSocket	ws
UI	GlitchCN/UI (shadcn-based)

API

WebSocket Protocol

Connect to ws://localhost:3000/ws?sessionId={optional} for real-time terminal I/O.

Binary messages (for terminal I/O):

• Format: [type:1][paneIdLength:1][paneId:N][payload:M]
• Types: 0x01 INPUT, 0x02 OUTPUT

JSON messages (for control):

• resize, create, close, split, focus, broadcast

REST API

Endpoint	Method	Description
/health	GET	Health check
/api/v1/sessions	GET	List sessions
/api/v1/sessions	POST	Create session
/api/v1/sessions/:id	GET	Get session
/api/v1/sessions/:id	PATCH	Update session
/api/v1/sessions/:id	DELETE	Delete session
/api/v1/sessions/:id/save	POST	Save session
/api/v1/system/info	GET	System info

Configuration

Environment variables:

Variable	Default	Description
PORT	3000	Backend server port
HOST	localhost	Backend bind address
WEBTERM_DB_PATH	./data/webterm.db	SQLite database path
LOG_LEVEL	info	Logging level
MAX_PANES_PER_WINDOW	16	Maximum panes per window

Development

# Run linting
npm run lint

# Run type checking
npm run typecheck

# Run tests
npm test

# Format code
npm run format

Performance

WebTerm is optimized for low-latency terminal interaction:

• Input latency: < 50ms (binary WebSocket protocol)
• Render: 60fps (WebGL renderer)
• Scrollback: 10,000 lines per pane
• Bundle size: ~400KB gzipped
• Memory: < 200MB typical usage

License

MIT License - see LICENSE for details.

Acknowledgments

• xterm.js - Terminal emulation
• node-pty - PTY management
• GlitchCN/UI - UI components
• tmux - Inspiration for keybindings