61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# 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.
|