name: charm-crush description: Architecture patterns from Crush, charmbracelet's production agentic coding CLI built on bubbletea v2, lipgloss v2, bubbles v2, glamour v2, and ultraviolet. Use when building production bubbletea apps, composing charm TUI components at scale, designing agentic CLI tools, implementing streaming LLM UIs, or asking about crush internals. NOT for individual charm library basics. argument-hint: "[pattern or component to look up]"

Charm Crush - Production Agentic TUI Patterns

Crush is charmbracelet's agentic coding CLI - their answer to Claude Code, built entirely with their own TUI stack. This skill captures the architecture patterns, component composition strategies, and design decisions from a production app with 10+ composed components, real-time LLM streaming, dialog overlays, and a full agent loop.

Source: github.com/charmbracelet/crush (FSL-1.1-MIT)

Architecture Overview

Crush follows a clear layered architecture:

main.go (cobra CLI)
  -> internal/app/app.go (wiring: DB, config, agents, LSP, MCP, events)
    -> internal/agent/ (LLM conversations, tool execution, streaming)
    -> internal/ui/ (bubbletea v2 TUI)
    -> internal/permission/ (tool approval via pubsub)
    -> internal/skills/ (Agent Skills open standard)
    -> internal/pubsub/ (generic typed broker for cross-component messaging)
    -> internal/session/ (SQLite persistence via sqlc)

Key Dependencies (go.mod)

Decision Tree: How Crush Solves Common Problems

Use $ARGUMENTS to find the relevant pattern, or browse by category:

TUI Architecture

• "How do I structure a large bubbletea app?" -> Read references/tui-patterns.md (Centralized Model pattern)
• "How do I handle window resize?" -> Read references/tui-patterns.md (Layout System)
• "How do I compose 10+ components?" -> Read references/component-composition.md
• "How do I manage focus between panes?" -> Read references/tui-patterns.md (Focus Management)
• "How do I render streaming content?" -> Read references/tui-patterns.md (Streaming Rendering)
• "How do I do overlays/modals?" -> Read references/component-composition.md (Dialog System)

Agent Loop

• "How does the LLM loop work?" -> Read references/agent-loop.md
• "How do I handle tool approval?" -> Read references/agent-loop.md (Permission System)
• "How do I stream LLM responses to the TUI?" -> Read references/agent-loop.md (Streaming Bridge)

Design & Styling

• "How do I build a polished terminal UI?" -> Read references/design-system.md
• "What colors does charm use?" -> Read references/design-system.md (Charmtone Palette)
• "How do I structure styles for a large app?" -> Read references/design-system.md (Styles Struct)

Core Pattern: The Centralized Model

The single most important architectural decision in Crush. The UI struct in internal/ui/model/ui.go is the sole bubbletea model. Sub-components are NOT bubbletea models - they're stateful structs with imperative methods.

UI (the only tea.Model)
  |-- Chat (stateful struct, no Update method)
  |-- textarea (bubbles/v2 textarea.Model)
  |-- dialog.Overlay (stack of Dialog interfaces)
  |-- completions (non-standard Update returning bool)
  |-- attachments (non-standard Update)
  |-- status, header, pills (render methods on UI)

This means:

• All message routing happens in one giant switch msg.(type) in UI.Update()
• Focus state determines key routing (editor vs chat)
• Components expose methods like HandleMouseDown(), ScrollBy(), SetMessages() instead of Update(tea.Msg)
• Side effects return tea.Cmd from methods, not from Update

Why This Works

Traditional Elm architecture (each component gets its own Update/View) breaks down at scale because:

1. Message routing becomes a maze of forwarding
2. Shared state requires complex message passing
3. Focus management needs a central coordinator anyway

Crush sidesteps this by making the parent the single source of truth for all state transitions.

Rendering Pipeline: Ultraviolet Screen Buffer

Crush uses a hybrid rendering approach instead of pure string concatenation:

1. View() creates an ultraviolet.ScreenBuffer sized to terminal dimensions
2. Layout is computed as image.Rectangle regions via ultraviolet/layout.SplitVertical/SplitHorizontal
3. Components draw into sub-regions: uv.NewStyledString(str).Draw(scr, rect)
4. Dialogs draw last (overlay on top of everything)
5. canvas.Render() flattens to a string for bubbletea

This enables:

• Overlapping content (dialogs, completions popup)
• Precise cursor positioning across components
• Screen-based layout math instead of string width guessing

Communication: Typed Pub/Sub

Agent and TUI run on separate goroutines. They communicate through a generic typed broker (internal/pubsub) that publishes events which bubbletea converts to tea.Msg. See references/agent-loop.md for the full pattern and event types.

File Map

Reference Files

For detailed patterns with code examples from the actual source:

• references/tui-patterns.md - Layout system, focus management, key handling, streaming, responsive design
• references/agent-loop.md - Agent loop, fantasy SDK, tool system, permission flow, pubsub bridge
• references/design-system.md - Charmtone colors, Styles struct, icon system, typography
• references/component-composition.md - Interface hierarchy, dialog stack, list composition, chat items