Bubble Tea
Functional terminal UI framework for Go based on The Elm Architecture. Bubble Tea lets you build interactive terminal applications (TUIs) with a model-update-view pattern: define a Model struct, a Update function (handles messages/events), and a View function (renders to string). Part of Charmbracelet's TUI ecosystem — pairs with Lip Gloss (styling/layout), Bubbles (reusable TUI components — spinners, progress bars, text inputs, tables), and Huh (terminal forms). Used in production CLIs by GitHub, Mage, and hundreds of Go projects.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Terminal app — no network exposure from TUI itself. No user data sent externally. CLI security is application responsibility. Terminal input handling should sanitize for shell injection if passing to subprocesses.
⚡ Reliability
Best When
You're building interactive Go CLI tools that need real-time updates, user input handling, complex layouts, or animation in the terminal — Bubble Tea's Elm Architecture keeps complex TUI code organized.
Avoid When
Your CLI just runs and exits (use cobra/flag), you need a GUI window, or your target users primarily use Windows CMD where terminal rendering is inconsistent.
Use Cases
- • Build interactive agent CLI tools with real-time progress displays using Bubble Tea — show agent task status, spinner animations, and streaming output in terminal
- • Create terminal dashboards for agent monitoring using Bubble Tea + Lip Gloss — color-coded status tables, progress bars, and scrollable log views without a GUI framework
- • Implement interactive agent configuration wizards using Huh (Charmbracelet forms) — multi-step terminal forms for agent setup with validation and confirmation
- • Build agent REPL interfaces with syntax highlighting and history using Bubble Tea — interactive command interpreters for agent orchestration from terminal
- • Display real-time agent pipeline visualization in terminal — animated pipeline stages, concurrent task status, and streaming inference output for developer tools
Not For
- • GUI applications with mouse-heavy interaction or graphical rendering — Bubble Tea is terminal-based; use Fyne or Wails for window-based GUI apps
- • Simple one-shot CLI tools that don't need interactivity — cobra or flag package is sufficient for non-interactive CLIs; Bubble Tea adds complexity only justified for interactive experiences
- • Web or browser-based dashboards — Bubble Tea is terminal-only; use React or a web framework for browser-based agent monitoring UIs
Interface
Authentication
TUI framework — no auth concepts. Auth for external services handled in Go application logic behind the TUI.
Pricing
Bubble Tea is MIT licensed, maintained by Charmbracelet. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Background goroutines must send messages via tea.Cmd — spawning goroutines that directly mutate model state is wrong; return tea.Cmd from Update that wraps background work and sends result as tea.Msg
- ⚠ Terminal size changes arrive as tea.WindowSizeMsg — layouts that don't handle WindowSizeMsg render incorrectly after terminal resize; subscribe to WindowSizeMsg and update model width/height
- ⚠ Alt screen vs inline mode — tea.WithAltScreen() uses alternate terminal buffer (full-screen app); without it, TUI renders inline in terminal history; choose based on whether app should be full-screen or scrollable
- ⚠ Lip Gloss width calculations with Unicode — Lip Gloss Width() function may miscalculate width for emoji and certain Unicode characters; use runewidth.StringWidth for accurate CJK/emoji column counting
- ⚠ Program blocking vs async — p.Run() blocks until program exits; spawn Bubble Tea program in goroutine if it runs alongside other app logic; p.Send() allows external goroutines to push messages into the TUI event loop
- ⚠ Testing Bubble Tea models requires direct Update calls — no standard Bubble Tea testing framework; test Update() function directly by constructing messages and checking returned Model state; don't rely on visual output for tests
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Bubble Tea.
Scores are editorial opinions as of 2026-03-06.