Files

T

izackp 3e0c9f87c8 feat: dock mobile keybar to bottom of screen with larger touch targets

The mobile keybar was a small floating overlay that obscured terminal
content. Now it's a full-width bar docked to the bottom using flexbox
layout, so the terminal shrinks to accommodate it. Buttons use 44px
height (Apple HIG recommended touch target) and evenly fill the width.
Also uses 100dvh for correct mobile viewport sizing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-08 04:06:45 -04:00

3.0 KiB

Raw Blame History

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