webterm/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is webterm

A Go server that exposes terminal sessions over HTTP/WebSocket, with a dashboard mode for multiple sessions showing live-updating terminal tiles. Uses Ghostty WebAssembly for terminal rendering in the browser.

Build Commands (always use Makefile)

Never run raw go test, go vet, or bun commands directly.

• make check — lint + tests + coverage (run before and after changes)
• make race — run Go tests with race detector
• make test — run Go tests only
• make lint — run go vet
• make format — run gofmt
• make fuzz — run all fuzz targets briefly
• make build — build frontend (TypeScript typecheck + bun bundle)
• make build-fast — build frontend without typecheck
• make build-go — build Go CLI binary to bin/webterm
• make build-all — full reproducible build from scratch
• make bundle-watch — watch mode for frontend development
• make install-dev — install Go and frontend dependencies
• make bump-patch — bump patch version, commit, and tag

Run go run ./cmd/webterm to start the server on port 8080.

Architecture

Go backend (webterm/ package): HTTP/WebSocket server with PTY-backed terminal sessions.

• cli.go — CLI flag parsing and startup orchestration
• server.go — HTTP router, WebSocket handler, SSE events, screenshot cache
• session.go — Session interface and SessionConnector interface for bidirectional session I/O
• terminal_session.go — TerminalSession: PTY-backed local session using creack/pty
• docker_exec_session.go — Docker exec-based sessions (attach to running containers)
• session_manager.go — manages session lifecycle (create, lookup, cleanup)
• docker_watcher.go / docker_http.go — Docker API integration for auto-discovering containers with webterm-command labels
• replay.go — ring buffer that captures terminal output for reconnect replay
• internal/terminalstate/tracker.go — VT state tracker using go-te for generating screenshots
• svg_exporter.go / png_exporter.go — render terminal state to SVG/PNG for dashboard thumbnails
• config.go — YAML manifest parsing for landing/compose modes

Frontend (webterm/static/js/terminal.ts): Single TypeScript file bundled with bun. Uses ghostty-web WASM for terminal rendering. Handles WebSocket connection, reconnect, virtual keyboard, theme/font controls.

Static assets are embedded into the Go binary via assets_embed.go (go:embed). Override at runtime with WEBTERM_STATIC_PATH.

Entry point: cmd/webterm/main.go calls webterm.RunCLI().

Key Patterns

• Sessions implement the Session interface; two implementations: TerminalSession (local PTY) and DockerExecSession
• The SessionConnector interface decouples session I/O from the WebSocket layer
• Docker integration uses raw HTTP against the Docker socket (no Docker SDK dependency)
• Version is read from the VERSION file and injected via -ldflags at build time

Debugging Rule

Before making a second patch for the same bug, identify the exact callsite that causes the side effect. Trace the real owner of the behavior end-to-end, including dependency code such as ghostty-web when necessary, instead of stacking app-level symptom fixes.