agentleFS
nikshipsnikships/skills-registry/.agents/skills/building-glamorous-tuis/SKILL.md

building-glamorous-tuis

Skill25 starsChanged 6 months agoApache-2.0View on GitHub

Build terminal UIs with Charmbracelet (Bubble Tea, Lip Gloss, Gum). Use when: Go TUI, shell prompts/spinners, "make CLI prettier", adaptive layouts, async rendering, focus state machines, sparklines, heatmaps, kanban boards, SSH apps.

  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 2

    1. Dicklesworthstone/meta_skill★ 214100% same
    2. Dicklesworthstone/remote_compilation_helper★ 69100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository6 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    CI/CD: No terminal → use flags/env vars

    line 269

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Building Glamorous TUIs with Charmbracelet

Quick Router — Start Here

I need to...UseReference
Add prompts/spinners to a shell scriptGum (no Go)Shell Scripts
Build a Go TUIBubble Tea + Lip GlossGo TUI
Build a production-grade Go TUIAbove + elite patternsProduction Architecture
Serve a TUI over SSHWish + Bubble TeaInfrastructure
Record a terminal demoVHSShell Scripts
Find a Bubbles componentlist, table, viewport, spinner, progress...Component Catalog
Get a copy-paste patternLayouts, forms, animation, testingQuick Reference / Advanced Patterns

Decision Guide

Is it a shell script?
├─ Yes → Use Gum
│        Need recording? → VHS
│        Need AI? → Mods
│
└─ No (Go application)
   │
   ├─ Just styled output? → Lip Gloss only
   ├─ Simple prompts/forms? → Huh standalone
   ├─ Full interactive TUI? → Bubble Tea + Bubbles + Lip Gloss
   │  │
   │  └─ Production-grade?  → Also add elite patterns:
   │     (multi-view, data-    two-phase async, immutable snapshots,
   │      dense, must be       adaptive layout, focus state machine,
   │      fast & polished)     semantic theming, pre-computed styles
   │                           → See Production Architecture reference
   │
   └─ Need SSH access? → Wish + Bubble Tea

Shell Scripts (No Go Required)

brew install gum  # One-time install
# Input
NAME=$(gum input --placeholder "Your name")

# Selection
COLOR=$(gum choose "red" "green" "blue")

# Fuzzy filter from stdin
BRANCH=$(git branch | gum filter)

# Confirmation
gum confirm "Continue?" && echo "yes"

# Spinner
gum spin --title "Working..." -- long-command

# Styled output
gum style --border rounded --padding "1 2" "Hello"

Full Gum Reference → VHS Recording → Mods AI →


Go Applications

go get github.com/charmbracelet/bubbletea github.com/charmbracelet/lipgloss

Minimal TUI (Copy & Run)

package main

import (
    "fmt"
    tea "github.com/charmbracelet/bubbletea"
    "github.com/charmbracelet/lipgloss"
)

var highlight = lipgloss.NewStyle().Foreground(lipgloss.Color("212")).Bold(true)

type model struct {
    items  []string
    cursor int
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "up", "k":
            if m.cursor > 0 { m.cursor-- }
        case "down", "j":
            if m.cursor < len(m.items)-1 { m.cursor++ }
        case "enter":
            fmt.Printf("Selected: %s\n", m.items[m.cursor])
            return m, tea.Quit
        }
    }
    return m, nil
}

func (m model) View() string {
    s := ""
    for i, item := range m.items {
        if i == m.cursor {
            s += highlight.Render("▸ "+item) + "\n"
        } else {
            s += "  " + item + "\n"
        }
    }
    return s + "\n(↑/↓ move, enter select, q quit)"
}

func main() {
    m := model{items: []string{"Option A", "Option B", "Option C"}}
    tea.NewProgram(m).Run()
}

Library Cheat Sheet

NeedLibraryExample
TUI frameworkbubbleteatea.NewProgram(model).Run()
Componentsbubbleslist.New(), textinput.New()
Stylinglipglossstyle.Foreground(lipgloss.Color("212"))
Formshuhhuh.NewInput().Title("Name").Run()
Markdownglamourglamour.Render(md, "dark")
Animationharmonicaharmonica.NewSpring()

Full Go TUI Guide → All Bubbles Components → Layout & Animation Patterns →


SSH Apps (Infrastructure)

s, _ := wish.NewServer(
    wish.WithAddress(":2222"),
    wish.WithHostKeyPath(".ssh/key"),
    wish.WithMiddleware(
        bubbletea.Middleware(handler),
        logging.Middleware(),
    ),
)
s.ListenAndServe()

Connect: ssh localhost -p 2222

Full Infrastructure Guide →


Production TUI Architecture (Elite Patterns)

Beyond basic Bubble Tea: patterns that make TUIs feel fast, polished, and professional. Each links to a full code example in Production Architecture.

My TUI is slow or janky

SymptomPatternFix
UI blocks during computationTwo-Phase AsyncPhase 1 instant, Phase 2 background goroutine
Render path holds mutexImmutable SnapshotsPre-build snapshot, atomic pointer swap
File changes cause stutterBackground WorkerDebounced watcher + coalescing
Thousands of allocs per framePre-Computed StylesAllocate delegate styles once at startup
O(n²) string concat in View()strings.BuilderPre-allocated Builder with Grow()
Glamour re-renders every frameCached MarkdownCache by content hash, invalidate on width change
GC pauses during interactionIdle-Time GCTrigger GC during idle periods
Large dataset = high memoryObject Poolingsync.Pool with pre-allocated slices
Rendering off-screen itemsViewport VirtualizationOnly render visible rows

My layout breaks on different terminals

SymptomPatternFix
Hardcoded widths breakAdaptive Layout3-4 responsive breakpoints (80/100/140/180 cols)
Colors wrong on light terminalsSemantic Theminglipgloss.AdaptiveColor + WCAG AA contrast
Items have equal priority → list shufflesDeterministic SortingStable sort with tie-breaking secondary key
Sort mode not visibleDynamic Status BarLeft/right segments with gap-fill

My TUI has multiple views and it's getting messy

SymptomPatternFix
Key routing chaosFocus State MachineExplicit focus enum + modal priority layer
User gets lost in nested viewsBreadcrumb NavigationHome > Board > Priority path indicator
Overlay dismiss loses positionFocus RestorationSave focus before overlay, restore on dismiss
Old async results overwrite new dataStale Message DetectionCompare data hash before applying results
Multiple component updates per frametea.Batch AccumulationCollect cmds in slice, return tea.Batch(cmds...)
Background goroutine panic kills TUIError Recoverydefer/recover wrapper for all goroutines

I want to add data-rich visualizations

WantPatternCode
Bar charts in list columnsUnicode Sparklines▇▅▂ using 8-level block characters
Color-by-intensityPerceptual Heatmapsgray → blue → purple → pink gradient
Dependency graph in terminalASCII Graph RendererCanvas + Manhattan routing (╭─╮│╰╯)
Age at a glanceAge Color CodingFresh=green, aging=yellow, stale=red
Borders that mean somethingSemantic BordersRed=blocked, green=ready, yellow=high-impact

I want my TUI to feel polished and professional

WantPatternKey Idea
Vim-style gg/GVim Key CombosTrack waitingForG state between keystrokes
Search without jankDebounced Search150ms timer, fire only when typing stops
Search across all fields at onceComposite FilterValueFlatten all fields into one string
4-line cards with metadataRich DelegatesCustom delegate with Height()=4
Expand detail inlineInline ExpansionToggle with d, auto-collapse on j/k
Copy to clipboardClipboard Integrationy for ID, C for markdown + toast feedback
? / ` / ; helpMulti-Tier HelpQuick ref + tutorial + persistent sidebar
Kanban with mode switchingKanban SwimlanesPre-computed board states, O(1) switch
Collapsible tree with h/lTree NavigationFlatten tree to visible list for j/k nav
Suspend TUI for vim editEditor Dispatchtea.ExecProcess for terminal, background for GUI
Remember expand/collapsePersistent StateSave to JSON, graceful degradation on corrupt
Tune via env varsEnv PreferencesNO_COLOR, theme, debounce, split ratio
Optional feature missing?Graceful DegradationDetect at startup, hide unavailable features

Full Production Architecture Guide →


Pre-Flight Checklist (Every TUI)

  • Handle tea.WindowSizeMsg — resize all components
  • Handle ctrl+c — cleanup, restore terminal state
  • Detect piped stdin/stdout — fall back to plain text
  • Test on 80×24 minimum terminal
  • Provide --no-tui / NO_TUI escape hatch
  • Test with both light AND dark backgrounds
  • Test with NO_COLOR=1 and TERM=dumb

For production TUIs, see the full checklist (16 must-have + 20 polish items).


When NOT to Use Charm

  • Output is piped: mytool | grep → plain text
  • CI/CD: No terminal → use flags/env vars
  • One simple prompt: Maybe fmt.Scanf is fine

Escape hatch:

if !term.IsTerminal(os.Stdin.Fd()) || os.Getenv("NO_TUI") != "" {
    runPlainMode()
    return
}

All References

I need...Read this
Copy-paste one-linersQuick Reference
Prompts to give Claude for TUI tasksPrompts
Gum / VHS / Mods / Freeze / GlowShell Scripts
Bubble Tea architecture, debugging, anti-patternsGo TUI
Bubbles component APIs (list, table, viewport...)Component Catalog
Theming, layouts, animation, Huh forms, testingAdvanced Patterns
Elite patterns: async, snapshots, focus machines, adaptive layout, sparklines, kanban, trees, cachingProduction Architecture
Wish SSH server, Soft Serve, teatestInfrastructure

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.