charm-tui

name

charm-tui

description

Charmbracelet v2 TUI stack for Go: Bubble Tea (Elm architecture), Bubbles components, Lip Gloss styling and layout, Huh forms, Glamour markdown, fang CLI wrapper, testing with golden files and teatest. Invoke whenever task involves any interaction with terminal UIs in Go — building, reviewing, debugging, or testing TUI applications, bubbletea programs, terminal styling, keybindings, forms, or interactive terminal output.

charm-tui

Terminal UIs in Go with the Charmbracelet v2 stack: Bubble Tea (Elm-architecture framework), Bubbles (components), Lip Gloss (styling/layout), Huh (forms), Glamour (markdown), fang (CLI entry), log. This skill documents v2 only — model training data is saturated with v1 code, and v1 idioms either fail to compile or silently misbehave against v2. When in doubt, this skill and the local go.mod win over remembered API shapes.

• Import paths: charm.land/bubbletea/v2, charm.land/bubbles/v2/..., charm.land/lipgloss/v2, charm.land/huh/v2, charm.land/glamour/v2, charm.land/fang/v2, charm.land/log/v2. Exceptions on GitHub paths: github.com/charmbracelet/ultraviolet, github.com/charmbracelet/x/..., github.com/charmbracelet/colorprofile. github.com/charmbracelet/bubbletea and friends resolve to v1 — never import them.
• View() returns tea.View, a struct — not a string. Wrap content with tea.NewView(s).
• Terminal features are declarative View fields set on every render (v.AltScreen, v.MouseMode, v.Cursor, v.WindowTitle, …). There are no tea.WithAltScreen() options or tea.EnterAltScreen commands.
• Key presses arrive as tea.KeyPressMsg (tea.KeyMsg is an interface that also matches releases). The space bar is "space" in msg.String(), not " ".
• Update is pure: no I/O or expensive work — do it in a tea.Cmd. Commands run on other goroutines and must never mutate the model — they return a message; Update applies it.

References

• Bubble Tea core — ${CLAUDE_SKILL_DIR}/references/bubbletea.md — full tea.View field catalog, program options, command/message catalogs, keyboard (Kitty enhancements) and mouse details, exec/suspend, errors/panics, framework gotchas
• Bubbles components — ${CLAUDE_SKILL_DIR}/references/bubbles.md — per-component APIs (textinput, textarea, viewport, table, list, spinner, progress, timer, filepicker, paginator, help, key), real-cursor wiring, component gotchas
• Lip Gloss styling — ${CLAUDE_SKILL_DIR}/references/lipgloss.md — Style API, color system, measurement, join/place layout, borders, layer compositing (overlays, hit-testing), table/tree/list sub-packages, standalone output writers
• Huh forms + Glamour markdown — ${CLAUDE_SKILL_DIR}/references/forms-and-markdown.md — field types, validation, dynamic forms, themes, accessibility, bubbletea embedding; glamour styles, options, viewport integration
• Architecture at scale — ${CLAUDE_SKILL_DIR}/references/architecture.md — the crush patterns: single-model architecture, imperative children, ultraviolet hybrid rendering, dialog overlay stack, virtualized lists with render caching, async/streaming integration
• Ecosystem and testing — ${CLAUDE_SKILL_DIR}/references/ecosystem-and-testing.md — fang, log, ultraviolet positioning, x/ packages, golden View tests, teatest v2, tmux-driven verification

The Core Model

Every Bubble Tea program is three methods on a model:

package main

import (
    "fmt"
    "os"

    tea "charm.land/bubbletea/v2"
)

type model struct {
    count int
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyPressMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "space":
            m.count++
        }
    case tea.MouseClickMsg:
        if msg.Button == tea.MouseLeft {
            m.count++
        }
    }
    return m, nil
}

func (m model) View() tea.View {
    v := tea.NewView(fmt.Sprintf("Count: %d\n\nspace/click to increment · q to quit\n", m.count))
    v.AltScreen = true
    v.MouseMode = tea.MouseModeCellMotion
    return v
}

func main() {
    if _, err := tea.NewProgram(model{}).Run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

• Init() tea.Cmd returns the first command (nil is fine). Some stale doc comments show a two-value Init signature — it does not compile; the interface is Init() Cmd.
• Set View fields on every return path of View() — a forgotten v.AltScreen = true on an early return exits the alt screen for that frame.
• ctrl+c is not handled automatically — raw mode delivers it as a key press; always handle it or users cannot interrupt.

Commands and Messages

• A tea.Cmd is func() tea.Msg. Do I/O inside, return a custom message type, mutate state in Update when it arrives. Prefer named model methods over inline closures for commands.
• Message-returning functions are passed uninvoked: return m, tea.Quit — not tea.Quit(). Same for tea.Suspend, tea.RequestWindowSize, tea.RequestBackgroundColor, tea.ClearScreen.
• tea.Batch(cmds...) runs concurrently with no ordering guarantee; tea.Sequence(cmds...) runs in order. Use Sequence when order matters.
• tea.Tick/tea.Every fire once — re-return the command from Update on each tick to keep a timer alive.
• Inject external events with p.Send(msg) from any goroutine (pubsub bridges, servers, watchers).
• tea.Println/tea.Printf output is invisible while AltScreen is active — debug with tea.LogToFile instead.

Input Handling

Match tea.KeyPressMsg and switch on msg.String() ("enter", "ctrl+c", "space", "up"); field matching (msg.Code == 'c' && msg.Mod == tea.ModCtrl) is the foolproof alternative. For real applications, define a keymap of key.Bindings (charm.land/bubbles/v2/key) so bindings are declared once and the help view renders itself:

keys := struct{ Up, Quit key.Binding }{
    Up:   key.NewBinding(key.WithKeys("up", "k"), key.WithHelp("↑/k", "up")),
    Quit: key.NewBinding(key.WithKeys("q", "ctrl+c"), key.WithHelp("q", "quit")),
}
// Update: case tea.KeyPressMsg: switch { case key.Matches(msg, keys.Up): ... }

Mouse: enable via v.MouseMode, match tea.MouseClickMsg/MouseWheelMsg/MouseMotionMsg. Paste arrives as tea.PasteMsg, never as a key message.

Styling

• Lip Gloss Style is an immutable value — every setter returns a copy; build once, store, derive variants by assignment. Under Bubble Tea, just return styled strings from View(); downsampling is automatic.
• Measure with lipgloss.Width/Height(str) (ANSI- and wide-char-aware); constrain with Style.Width/Height(n). Never len() on styled strings; for cutting/truncating styled text use github.com/charmbracelet/x/ansi (ansi.Truncate, ansi.Cut, ansi.StringWidth) — byte slicing corrupts escape sequences.
• Compose layouts with lipgloss.JoinHorizontal/JoinVertical(pos, blocks...) and lipgloss.Place(w, h, hPos, vPos, content).
• Colors are explicit in v2 — there is no automatic light/dark adaptation and no AdaptiveColor. Bootstrap theme detection through the event loop:

func (m model) Init() tea.Cmd { return tea.RequestBackgroundColor }

// Update:
case tea.BackgroundColorMsg:
    m.styles = newStyles(msg.IsDark()) // build all styles once from isDark

func newStyles(isDark bool) styles {
    lightDark := lipgloss.LightDark(isDark)
    title := lipgloss.NewStyle().Foreground(lightDark(lipgloss.Color("#333"), lipgloss.Color("#eee")))
    // ...
}

• Centralize styles in one semantic struct built from isDark, threaded to components — no color literals scattered through render code.

Layout Discipline

• Subtract frame sizes before rendering content: contentW := termW - style.GetHorizontalFrameSize(). A bordered panel consumes 2 cells per axis; forgetting this breaks every layout.
• Track terminal size from tea.WindowSizeMsg (sent at startup and on resize) and size children from it. There are no resize events on Windows.
• Truncate explicitly (ansi.Truncate) instead of relying on wrap inside fixed-size panels.
• Size panels with proportional weights from the terminal size, not fixed cell counts.
• Emoji and some CJK render 1 or 2 cells depending on the terminal — avoid variation-selector emoji in width-critical chrome.

Components (Bubbles)

Value-type models: New(...) → forward messages with m.child, cmd = m.child.Update(msg) (returns the concrete type — reassign!) → compose View() strings. Interactive components need Focus() (returns a tea.Cmd — dispatch it) and silently ignore input when unfocused.

• textinput / textarea — single/multiline input; styles set via SetStyles(DefaultStyles(isDark))
• viewport — scrollable content window; zero-value size renders nothing — set dimensions before first render
• table — navigable rows; needs WithFocused(true); fixed column widths
• list — filterable item list with batteries (pagination, spinner, help)
• spinner / progress / timer / stopwatch — animated; keep re-returning their tick/frame commands
• help — renders keymaps implementing ShortHelp/FullHelp
• filepicker / paginator / cursor — file selection, page math, cursor primitive

Every component defaults to dark styles — apply DefaultStyles(isDark) after background detection or light terminals render wrong. Full APIs and per-component gotchas: see the bubbles reference.

Forms and Markdown

• Huh for any form/prompt flow — standalone (form.Run()) or embedded in a bubbletea app (type-assert form.(*huh.Form) after Update, wrap form.View() in tea.NewView, watch form.State == huh.StateCompleted). Bind values with .Value(&v). Themes: WithTheme(huh.ThemeFunc(huh.ThemeCharm)).
• Glamour for markdown → styled terminal output: glamour.NewTermRenderer(glamour.WithStylePath("dark"), glamour.WithWordWrap(width)). No auto style — pick "light"/"dark" from detected background; match word wrap to the viewport width and re-render on resize.

Architecture

• Small app (a screen, a few components) — standard Elm composition: root model owns bubbles models, forwards messages, concatenates views with lipgloss joins.
• Large app (screens, dialogs, streaming, long lists) — the stack authors' production pattern (crush): exactly one tea.Model; sub-components are plain structs with imperative methods (Render(width) string, mutators returning tea.Cmd) that the root calls; do not nest models. One switch msg.(type) routes everything; focus state decides key routing; dialogs are a stack drawn last and intercept input first.
• Either way: create files to separate logic; keep it simple. Full at-scale patterns (ultraviolet buffers, overlay stack, virtualized lists, streaming): see the architecture reference.

Testing

• Primary idiom — golden View tests: render the component directly, compare with golden.RequireEqual(t, []byte(ansi.Strip(m.View()))) (github.com/charmbracelet/x/exp/golden); regenerate with go test -update ./.... No tea.Program needed.
• Integration — teatest v2 (github.com/charmbracelet/x/exp/teatest/v2): drive a real program with tm.Type(...)/tm.Send(tea.KeyPressMsg{Code: tea.KeyEnter}). Always pin tea.WithColorProfile(colorprofile.Ascii) and teatest.WithInitialTermSize(w, h) for deterministic output.
• To watch it live, run the binary in tmux and tmux capture-pane -p the rendered frames.

Application

When writing charm TUI code:

• Apply all conventions silently — don't narrate rules being followed
• Check go.mod for the actual pinned versions before reaching for an API; verify uncertain signatures against the vendored module or pkg.go.dev/charm.land/... rather than memory
• If an existing codebase contradicts a convention, follow the codebase and flag the divergence once

When reviewing charm TUI code:

• Cite the specific violation and show the fix inline; don't lecture
• Treat v1 idioms (View() string, tea.KeyMsg switches, github.com/charmbracelet/bubbletea imports, tea.WithAltScreen()) as defects even when they "look right"

Integration

The golang skill governs Go implementation (errors, naming, structure, toolchain); this skill governs the charm TUI stack. The lipgloss table/tree/list sub-packages render static output for plain CLIs too — reach for them before hand-formatting aligned terminal output.

The renderer owns the terminal: state flows in as messages, the view is a pure declaration — code that fights either direction is wrong before it runs.