charm-crush

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)

Library	Version	Role
charm.land/bubbletea/v2	v2.0.2	TUI framework
charm.land/lipgloss/v2	v2.0.2	Terminal styling
charm.land/bubbles/v2	v2.0.0	Reusable components (textarea, viewport, spinner, help)
charm.land/glamour/v2	v2.0.0	Markdown rendering
charm.land/fantasy	v0.16.0	LLM provider abstraction (Anthropic, OpenAI, Gemini, Bedrock, etc.)
charmbracelet/ultraviolet	-	Screen-buffer rendering system
charm.land/catwalk	v0.31.0	Model registry + golden-file testing
charmbracelet/x/exp/charmtone	-	Color palette system

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

What	Where	Read for
Main TUI model	internal/ui/model/ui.go	Centralized model, Update loop, layout
Chat component	internal/ui/model/chat.go	List wrapping, animation, mouse handling
Tool renderers	internal/ui/chat/*.go	Per-tool rendering (bash, file, search, etc.)
Dialog system	internal/ui/dialog/	Modal overlays, permissions, models picker
List component	internal/ui/list/list.go	Lazy-rendered scrollable list
Styles	internal/ui/styles/styles.go	Full design system
Agent loop	internal/agent/agent.go	LLM streaming, tool execution
Coordinator	internal/agent/coordinator.go	Multi-provider setup, model management
Tool definitions	internal/agent/tools/*.go	Tool implementations (.go + .md pairs)
Permission system	internal/permission/permission.go	Tool approval flow
Skills loader	internal/skills/skills.go	SKILL.md parsing and discovery
Pub/sub	internal/pubsub/	Typed event broker
App wiring	internal/app/app.go	Service initialization
Config	internal/config/	crush.json loading, provider config
UI architecture guide	internal/ui/AGENTS.md	Charm's own UI development instructions

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