Charm Crush

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