Skip to main content
skill CX Codex

bubbletea-code-review — Claude Code skill

bubbletea-code-review reviews Go terminal UIs for Elm architecture, BubbleTea update flow, and Lipgloss styling. Use it when checking code built with charmbracelet/bubbletea.

Apache-2.0 270 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill bubbletea-code-review -a claude-code
Open on GitHub

What bubbletea-code-review does

This skill reviews terminal interfaces built with charmbracelet/bubbletea. It checks model state, message handling, Init, Update, and View, then looks for mutable state, missing WindowSizeMsg handling, incorrect tea.Quit usage, and broken child-component updates. It also checks sizing for Bubbles components and how Huh forms are embedded.

The review covers Lipgloss style placement and keyboard bindings through key.Matches and help.KeyMap. Before flagging tea.Cmd, value receivers, or nested child updates, the skill applies BubbleTea’s valid-pattern exceptions. Critical and major findings must include a file path and line, or a short code excerpt.

A direct os.ReadFile(), http.Get(), or time.Sleep() call inside Update() blocks the UI, so it is treated differently from a helper that only returns a tea.Cmd. Installation uses npx or gh, depending on the target platform.

What it helps with

  • review Elm architecture in a terminal UI
  • spot blocking I/O inside Update()
  • check whether model state stays immutable
  • verify resize handling with WindowSizeMsg
  • inspect Lipgloss styles and Bubbles components

Example prompts for the agent

  • Review this BubbleTea code for blocking I/O and give file-and-line evidence for every major finding.
  • Check internal/tui/model.go for correct Model/Update/View flow and Lipgloss usage.
  • Inspect how this TUI updates its Bubbles children and embeds the Huh form.

How to install bubbletea-code-review

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill bubbletea-code-review -a claude-code

2Manually: put the files in place

~/.claude/skills/bubbletea-code-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bubbletea-code-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bubbletea-code-review

How do I install bubbletea-code-review in Claude Code?

Run npx skills add existential-birds/beagle --skill bubbletea-code-review -a claude-code, then check ~/.claude/skills/bubbletea-code-review/SKILL.md.

What does bubbletea-code-review do?

It reviews BubbleTea terminal UI code for Elm architecture, correct Model/Update/View behavior, command handling, and Lipgloss styling.

Which blocking calls does it flag in Update()?

It flags direct os.ReadFile(), http.Get(), time.Sleep(), blocking channel reads, and huh.Form.Run() inside Update(). Helpers that only return a tea.Cmd are treated as valid.

Source text

SKILL.md · Apache-2.0
---
name: bubbletea-code-review
description: Reviews BubbleTea TUI code for proper Elm architecture, model/update/view patterns, and Lipgloss styling. Use when reviewing terminal UI code using charmbracelet/bubbletea.
---

# BubbleTea Code Review

## Hard gates (sequence)

Advance only when each **pass condition** is objectively true (reduces false positives on `tea.Cmd` and unsubstantiated blocking claims):

| Gate | Pass condition |
|------|----------------|
| **G1 — Anti–false-positive** | You skimmed **NOT Issues** below **or** read [references/elm-architecture.md](references/elm-architecture.md) **before** recording a finding about `tea.Cmd` returns, value receivers on `Update`, or nested child `Update`. |
| **G2 — Evidence for blocking / suspicious I/O** | Each Critical/Major finding names **file path + line** (or a short quoted snippet) showing the blocking call, `huh.Form.Run` in the wrong place, or other asserted anti-pattern—not a hypothetical. |
| **G3 — Verification** | Before publishing review output, you applied the **[review-verification-protocol](../review-verification-protocol/SKILL.md)** to each proposed finding. |

## Quick Reference

| Issue Type | Reference |
|------------|-----------|
| Elm architecture, tea.Cmd as data | [references/elm-architecture.md](references/elm-architecture.md) |
| Model state, message handling | [references/model-update.md](references/model-update.md) |
| View rendering, Lipgloss styling | [references/view-styling.md](references/view-styling.md) |
| Component composition, Huh forms | [references/composition.md](references/composition.md) |
| Bubbles components (list, table, etc.) | [references/bubbles-components.md](references/bubbles-components.md) |

## CRITICAL: Avoid False Positives

**Read [elm-architecture.md](references/elm-architecture.md) first!** The most common review mistake is flagging correct patterns as bugs.

### NOT Issues (Do NOT Flag These)

| Pattern | Why It's Correct |
|---------|------------------|
| `return m, m.loadData()` | `tea.Cmd` is returned immediately; runtime executes async |
| Value receiver on `Update()` | Standard BubbleTea pattern; model returned by value |
| Nested `m.child, cmd = m.child.Update(msg)` | Normal component composition |
| Helper functions returning `tea.Cmd` | Creates command descriptor, no I/O in Update |
| `tea.Batch(cmd1, cmd2)` | Commands execute concurrently by runtime |

### ACTUAL Issues (DO Flag These)

| Pattern | Why It's Wrong |
|---------|----------------|
| `os.ReadFile()` in Update | Blocks UI thread |
| `http.Get()` in Update | Network I/O blocks |
| `time.Sleep()` in Update | Freezes UI |
| `<-channel` in Update (blocking) | May block indefinitely |
| `huh.Form.Run()` in Update | Blocking call |

## Review Checklist

### Architecture
- [ ] **No blocking I/O in Update()** (file, network, sleep)
- [ ] Helper functions returning `tea.Cmd` are NOT flagged as blocking
- [ ] Commands used for all async operations

### Model & Update
- [ ] Model is immutable (Update returns new model, not mutates)
- [ ] Init returns proper initial command (or nil)
- [ ] Update handles all expected message types
- [ ] WindowSizeMsg handled for responsive layout
- [ ] tea.Batch used for multiple commands
- [ ] tea.Quit used correctly for exit

### View & Styling
- [ ] View is a pure function (no side effects)
- [ ] Lipgloss styles defined once, not in View
- [ ] Key bindings use key.Matches with help.KeyMap

### Components
- [ ] Sub-component updates propagated correctly
- [ ] Bubbles components initialized with dimensions
- [ ] Huh forms embedded via Update loop (not Run())

## Critical Patterns

### Model Must Be Immutable

```go
// BAD - mutates model
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    m.items = append(m.items, newItem)  // mutation!
    return m, nil
}

// GOOD - returns new model
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    newItems := make([]Item, len(m.items)+1)
    copy(newItems, m.items)
    newItems[len(m.items)] = newItem
    m.items = newItems
    return m, nil
}
```

### Commands for Async/IO

```go
// BAD - blocking in Update
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    data, _ := os.ReadFile("config.json")  // blocks UI!
    m.config = parse(data)
    return m, nil
}

// GOOD - use commands
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    return m, loadConfigCmd()
}

func loadConfigCmd() tea.Cmd {
    return func() tea.Msg {
        data, err := os.ReadFile("config.json")
        if err != nil {
            return errMsg{err}
        }
        return configLoadedMsg{parse(data)}
    }
}
```

### Styles Defined Once

```go
// BAD - creates new style each render
func (m Model) View() string {
    style := lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("205"))
    return style.Render("Hello")
}

// GOOD - define styles at package level or in model
var titleStyle = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("205"))

func (m Model) View() string {
    return titleStyle.Render("Hello")
}
```

## When to Load References

- **First time reviewing BubbleTea** → [elm-architecture.md](references/elm-architecture.md) (prevents false positives)
- Reviewing Update function logic → [model-update.md](references/model-update.md)
- Reviewing View function, styling → [view-styling.md](references/view-styling.md)
- Reviewing component hierarchy → [composition.md](references/composition.md)
- Using Bubbles components → [bubbles-components.md](references/bubbles-components.md)

## Review Questions

1. Is Update() free of blocking I/O? (NOT: "is the cmd helper blocking?")
2. Is the model immutable in Update?
3. Are Lipgloss styles defined once, not in View?
4. Is WindowSizeMsg handled for resizing?
5. Are key bindings documented with help.KeyMap?
6. Are Bubbles components sized correctly?

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for Code review and refactoring →

From the same set68

The whole set →
react-flow-code-review react-flow-code-review walks @xyflow/react code through a review checklist: anti-patterns, wasted re-renders, typing. Useful when a graph stutters or nodes keep remounting. CX Codex +1 329installs langgraph-architecture langgraph-architecture helps you choose how to structure a LangGraph application, manage state, and handle persistence. Use it when comparing LangGraph with simpler options or planning a multi-agent system. CX Codex +1 283installs swiftui-code-review swiftui-code-review audits SwiftUI code for view composition quality, state management patterns, list performance, and accessibility. Use it when reviewing files with @State, @Binding, @Observable, or view layout code. CX Codex +1 277installs tutorial-docs tutorial-docs is a Claude Code skill that structures learning-oriented tutorials using the Diataxis framework. The model applies it when creating getting-started guides and onboarding docs. CX Codex +1 273installs zustand-state zustand-state — a skill for Zustand, a lightweight state-management library for React and vanilla JavaScript. CX Codex +1 261installs dagre-react-flow dagre-react-flow configures automatic directed graph layouts in React Flow using dagre. It helps arrange hierarchical trees, process flows, and nodes across directional axes. CX Codex +1 257installs adr-writing adr-writing is a Claude Code skill that turns decisions into MADR-formatted ADRs and checks them against E.C.A.D.R. criteria. It also runs in Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 254installs swift-code-review swift-code-review is a Claude Code skill that checks Swift code for concurrency, error-handling, and memory issues. It activates for .swift reviews involving async/await, actors, or Sendable. CX Codex +1 253installs

Project sponsors

Companies that keep this analytics open