# 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.