Bubble Tea Admin & Architecture Guide

This guide is for developers, architects, and maintainers who embed Bubble Tea in a product, operate Bubble Tea–based programs, or need to understand how the framework works internally. It documents Bubble Tea v2 (charm.land/bubbletea/v2) at commit a23da80.

For task-oriented usage, see the companion User Guide. This document goes deeper: the runtime architecture, the event loop, the renderer, configuration, security posture, terminal-compatibility behavior, and how to extend or contribute to the project.

1. Executive Summary

Bubble Tea is a Go framework for terminal user interfaces, built on The Elm Architecture (Model–Update–View). It is a library, not an application: consumers import the tea package and build their own binaries. There is no server, no daemon, no configuration file, and no network surface — Bubble Tea runs in-process inside the host program and talks only to the controlling terminal (stdin/stdout) and OS signals.

What's notable in v2: a declarative View struct replaces v1's imperative options/commands for terminal features; a new high-performance cell renderer (ultraviolet); first-class keyboard/mouse with the Kitty protocol; native clipboard (OSC52); and a vanity module path (charm.land/...).

2. System Architecture

2.1 The Elm Architecture

Bubble Tea structures every program around three pure-ish functions on a single state value:

         ┌──────────────────────────────────────────────────────────┐
         │                       Program.Run()                       │
         │                                                           │
 stdin ─►│  TerminalReader (ultraviolet) ─► uv.Event ─► translate ─► │─► Msg
 (TTY)   │                                                           │     │
         │                          ┌────────────────┐              │     ▼
         │                          │   eventLoop()  │◄─────────────┼── p.msgs
         │   model.Update(msg) ◄────┤  (1 goroutine) │              │
         │        │                 └────────────────┘              │
         │        ├─► returns (Model, Cmd)                          │
         │        │                                                 │
         │        ▼                                                 │
         │   handleCommands(): cmd() runs in its OWN goroutine ─────┼─► p.Send(newMsg)
         │        │                                                 │
         │        ▼                                                 │
         │   render(model.View()) ─► renderer.render(View)          │
         │                              │                           │
         │                          ticker @ FPS ─► renderer.flush()│─► stdout (TTY)
         └──────────────────────────────────────────────────────────┘

Key properties:

• One update goroutine. eventLoop is the only place model.Update is called, so model mutation is serialized and race-free by construction — as long as you don't mutate the model from other goroutines.
• Commands are the I/O boundary. A Cmd is func() Msg. The loop hands each returned command to handleCommands, which runs it in a fresh goroutine and feeds its result back via p.Send. This is why slow work never blocks rendering.
• Rendering is decoupled. render just stores the latest View; a separate ticker goroutine flushes it to the terminal at the configured FPS (default 60, capped at 120).

2.2 The Model contract

type Model interface {
	Init() Cmd               // startup command (nil = none)
	Update(Msg) (Model, Cmd) // event → next state + optional command
	View() View              // state → declarative UI description
}

Msg is a type alias for ultraviolet.Event (type Msg = uv.Event), i.e. any value can be a message. Cmd is func() Msg.

Note

A few doc-comment examples inside the source (e.g. in color.go, keyboard.go) show Init() (Model, Cmd). That is a documentation inconsistency — the authoritative Model interface in tea.go defines Init() Cmd. The README and both tutorials use Init() Cmd. Implement Init() Cmd.

2.3 The Program runtime

tea.NewProgram(model, opts...) builds a *Program. Program.Run() is the blocking entry point that:

1. Resolves input (stdin or an opened TTY) and enters raw mode.
2. Detects terminal size and color profile; constructs the renderer (or nilRenderer if disabled).
3. Sends bootstrap messages: ColorProfileMsg, the initial WindowSizeMsg, and EnvMsg.
4. Runs model.Init() and dispatches the resulting command.
5. Starts the signal handler, resize listener, command processor, and renderer ticker.
6. Enters eventLoop until quit/kill/interrupt, then restores the terminal.

Program lifecycle methods:

2.4 Component composition

Bubble Tea has no widget system of its own; composition is a convention. A parent model embeds child component models, forwards messages to each child's Update, and stitches their View() strings together (typically with Lip Gloss). This recursion — "models all the way down" — is how large apps (and the entire Bubbles library) are built. See User Guide §8.

3. Source Layout

The library is a single Go package at the repository root. The rest of the tree is learning material and demos.

bubbletea/
├── tea.go              Program, Model, View, Cmd, NewProgram, Run, eventLoop
├── options.go          ProgramOption constructors (With…)
├── commands.go         Batch, Sequence, Tick, Every, RequestWindowSize
├── exec.go             Exec / ExecProcess (run external processes)
├── key.go              Key, KeyPressMsg/KeyReleaseMsg, key constants
├── keyboard.go         KeyboardEnhancements + KeyboardEnhancementsMsg
├── mouse.go            Mouse, MouseClickMsg/Release/Wheel/Motion, buttons
├── screen.go           WindowSizeMsg, ClearScreen, ModeReportMsg
├── cursor.go           Position, Cursor shapes, CursorPositionMsg
├── color.go / profile.go   Color query msgs, ColorProfileMsg
├── clipboard.go        OSC52 clipboard commands/messages
├── paste.go            Bracketed-paste messages
├── focus.go            FocusMsg / BlurMsg
├── environ.go          EnvMsg (environment over SSH)
├── raw.go              Raw escape-sequence command
├── termcap.go / xterm.go   Capability + terminal-version queries
├── logging.go          LogToFile / LogToFileWith
├── cursed_renderer.go  The cell-based renderer (ultraviolet-backed)
├── nil_renderer.go     No-op renderer (WithoutRenderer)
├── renderer.go         renderer interface, Println/Printf, FPS constants
├── tty*.go / termios*.go / signals_*.go   Per-OS terminal & signal plumbing
├── mod.go              KeyMod modifier constants
├── tutorials/          basics (MVU) + commands (I/O) — the canonical learning path
└── examples/           63 runnable demos (recipe gallery; not part of the API)

Note

The examples/ and tutorials/ directories are separate Go modules (examples, tutorial) with their own go.mod and a replace directive pointing at the parent. They are not imported by consumers and are excluded from the published library. They are, however, the best executable reference for real-world patterns.

4. The Event Loop in Detail

eventLoop (in tea.go) is the heart of the runtime. For each message it:

1. Translates raw input events (translateInputEvent) into typed tea.Msg values (key, mouse, paste, focus, color, capability, etc.).
2. Filters the message through the optional WithFilter function (which can rewrite or drop it).
3. Handles framework-internal messages before the model sees them — including QuitMsg, InterruptMsg, SuspendMsg, BatchMsg, sequenceMsg, WindowSizeMsg, clipboard/color requests, ClearScreen, Println, and ColorProfileMsg.
4. Calls model.Update(msg), capturing the returned model and command.
5. Dispatches the command to the command channel.
6. Renders the new View.

4.1 Concurrency & ordering

Important

Command goroutines are intentionally not awaited at shutdown — a long Tick could otherwise stall exit. They are allowed to leak until their function returns. Design commands to be cancellation-tolerant (e.g. honor a context you close).

4.2 Panic handling

By default Bubble Tea recovers from panics in the main loop and in command goroutines, restores the terminal, prints the stack trace (with \r\n line endings so it's readable in raw mode), and returns ErrProgramPanic wrapped in ErrProgramKilled. WithoutCatchPanics() disables this — which leaves the terminal in raw mode on panic, so use it only for debugging.

If TEA_DEBUG is truthy, the panic and stack are also written to bubbletea-panic-<unixtime>.log.

5. The Renderer

5.1 Cursed renderer (default)

cursed_renderer.go implements the production renderer. It is cell-based: it maintains a screen buffer (ultraviolet.ScreenBuffer), draws the View's styled content into it, and diffs against the last frame to emit the minimal set of escape sequences. Highlights:

• Frame-rate–driven flush. A ticker flushes at the configured FPS (default defaultFPS = 60, hard cap maxFPS = 120). Frames with no changes are skipped (viewEquals).
• Inline vs. alt screen. Inline mode renders relative to the cursor and grows/shrinks with content height; alt-screen mode uses a fixed full-window buffer and forces full redraws on resize.
• Synchronized output (mode 2026). On terminals known to support it, updates are wrapped in synchronized-output sequences to render atomically (no tearing). Apple Terminal and unreliable SSH sessions are excluded (shouldQuerySynchronizedOutput).
• Unicode core (mode 2027). When available, grapheme-width mode is enabled for correct wide-character/emoji widths.
• Cursor-movement optimizations. Hard tabs and backspace are used to shorten cursor moves where termios indicates support; scroll optimization is disabled on Windows due to terminal bugs.
• Keyboard protocol negotiation. Emits modifyOtherKeys and Kitty keyboard sequences; resets them when switching between main and alt screens (which have separate keyboard registries).
• Native progress bar, window title, FG/BG/cursor colors, bracketed paste, focus reporting, mouse modes are all reconciled by diffing the new View against the last one and emitting only the deltas.

5.2 Nil renderer

WithoutRenderer() installs nilRenderer, a no-op that discards all drawing. Output and logs then go straight to the writer with no redraw logic — for daemon-style programs or a non-interactive fallback when output isn't a TTY.

6. Configuration Reference

Bubble Tea has no config files. All configuration is via ProgramOption values passed to NewProgram, plus two environment variables read by the library.

6.1 Program options

6.2 Environment variables (read by the library)

Caution

Negative knowledge: TEA_LOGFILE, HELP_DEBUG, BUBBLETEA_LOG, and EDITOR appear in the codebase, but they are read by the example programs, not by the Bubble Tea library. Do not treat them as framework configuration. The library reads only TEA_TRACE and TEA_DEBUG.

6.3 Removed in v2 (negative knowledge)

These v1 APIs no longer exist. They are listed so you don't reach for them or document them as available:

• Options: WithAltScreen, WithMouseCellMotion, WithMouseAllMotion, WithReportFocus, WithoutBracketedPaste, WithInputTTY, WithANSICompressor.
• Commands: EnterAltScreen/ExitAltScreen, EnableMouseCellMotion/EnableMouseAllMotion/DisableMouse, HideCursor/ShowCursor, EnableBracketedPaste/DisableBracketedPaste, EnableReportFocus/DisableReportFocus, SetWindowTitle.
• Methods: p.Start(), p.StartReturningModel(), p.EnterAltScreen()/ExitAltScreen(), p.Enable/DisableMouse…(), p.SetWindowTitle().
• Renames: Sequentially → Sequence; WindowSize() (Cmd) → RequestWindowSize (Msg).

All terminal-feature toggles moved onto the View struct (AltScreen, MouseMode, WindowTitle, Cursor, ReportFocus, DisableBracketedPasteMode, KeyboardEnhancements).

7. Terminal Compatibility & Platform Behavior

Bubble Tea negotiates capabilities at runtime and degrades gracefully.

Tip

Recommend modern terminals (Ghostty, kitty, WezTerm, Alacritty, iTerm2, Windows Terminal) to users who need alt screen, true color, synchronized output, and key-release events. Test the same UI in Terminal.app and a basic xterm to confirm graceful degradation.

8. Security Analysis

Bubble Tea has a deliberately small attack surface — it is an in-process library with no network, no persistence, and no privileged operations. Still, integrators should be aware of:

Warning

The highest-risk integration points are Exec/ExecProcess (command injection if you interpolate untrusted input) and Raw (terminal-sequence injection). Both require you to supply the dangerous value, so the mitigation is input validation in your application code.

9. Operations

9.1 Building and shipping

A Bubble Tea program is a normal Go binary. Cross-compile with GOOS/GOARCH; ship the single artifact.

GOOS=linux  GOARCH=amd64 go build -o myapp-linux  .
GOOS=darwin GOARCH=arm64 go build -o myapp-darwin .
GOOS=windows GOARCH=amd64 go build -o myapp.exe   .

The repo itself releases via GoReleaser (.goreleaser.yml includes the shared Charm config) and runs lint/test through a Taskfile:

task lint   # golangci-lint run
task test   # go test -race -count 4 -cpu 1,4 ./...

9.2 Running over SSH

Serve TUIs remotely by wiring input/output to the SSH session and passing the client environment:

pty, _, _ := sess.Pty()
environ := append(sess.Environ(), "TERM="+pty.Term)
p := tea.NewProgram(model,
	tea.WithEnvironment(environ),
	tea.WithInput(sess),
	tea.WithOutput(sess),
)

Pair with Wish for the SSH server, auth, and session plumbing.

9.3 Graceful shutdown & external control

• Exit cleanly with the tea.Quit command (from Update) or p.Quit() (from outside).
• p.Kill() forces immediate teardown (returns ErrProgramKilled, skips the final render).
• WithContext(ctx) lets orchestration cancel the program; cancellation surfaces as ErrProgramKilled.
• Use p.Wait() to block until shutdown completes when coordinating multiple goroutines.

Caution

Known issue #1689: calling Kill() immediately after Run() can race. Prefer letting the program start, then Quit()/Kill(); or coordinate via a channel/WithContext.

9.4 Inspecting the runtime

• Trace log: set TEA_TRACE=/path/to/trace.log to capture an internal output trace.
• Panic log: set TEA_DEBUG=1 to write bubbletea-panic-*.log on panic.
• App log: use tea.LogToFile("debug.log", "debug") and tail -f it (you can't log to stdout — the TUI owns it).

10. Error & Message Reference

10.1 Sentinel errors from Run()

Other wrapped errors surface from terminal setup/teardown (opening the TTY, entering raw mode, restoring console state, getting terminal size) and from renderer flush/close paths — all prefixed bubbletea: or describing the failing terminal operation.

10.2 Framework messages (selected)

11. Code Quality & Conventions

12. Potential Improvements & Known Issues

From the issue tracker and source review at a23da80:

• Kill()-after-Run() data race (#1689, open). Tighten the startup/teardown handshake so an immediate kill is safe.
• Textarea infinite loop on alt+left with empty input (#1652, open). A component-level edge case (Bubbles) exposed through Bubble Tea input.
• Emoji/flag width breaks tables (#1646, open) & hard-tab cursor optimization misaligns columns (#1614, closed). Display-width correctness across terminals remains the thorniest area; the Unicode-core (2027) negotiation mitigates but doesn't fully solve it.
• Renderer mangles output on some terminals (#1564, open) / sneaky rendering (#1671, closed). Long tail of terminal-specific rendering quirks; the cell renderer + synchronized output reduces but doesn't eliminate them.
• Garbage chars on too-early quit (#1590, open). Ensure all queued sequences flush before exit when the program quits very quickly.
• examples/go.mod replace directive breaks go run …/examples/...@latest (#1681, open). Packaging nit for the examples module.
• Proposed tooling (#1655 devtools inspector, #1654 testing framework). Community interest in a Bubble Tea inspector and an official testing harness — promising directions for operability.

Note

None of these are security defects; they are rendering-correctness and lifecycle edge cases inherent to driving heterogeneous terminals. Track the open issues for your target terminals before relying on bleeding-edge features (key release, synchronized output, native progress bars).

13. Extending & Contributing

• Build a component: implement the same Init/Update/View shape as a sub-model and expose it for embedding — the Bubbles library is the reference implementation pattern.
• Add terminal features: they generally surface as (a) a new View field reconciled in cursed_renderer.go, plus (b) a message type translated in input.go. Follow the existing diff-and-emit pattern.
• Custom renderer: implement the unexported renderer interface (render, flush, resize, setColorProfile, insertAbove, onMouse, …) if you need a bespoke backend; nilRenderer is the minimal template.
• Local development: use the Taskfile (task lint, task test). Tests are race-enabled with golden files — regenerate goldens deliberately, never blindly.
• Contribution entry point: the repo's contribute page (linked from the README). Match the strict lint config and add golden/race tests for rendering changes.

The Admin-level takeaway: Bubble Tea is small, composable, and terminal-faithful. Its complexity lives almost entirely in the renderer and per-terminal negotiation; the application-facing API is a tight, well-tested MVU core that you extend by composition, not configuration.