# Charm Tui Builder

> Build idiomatic terminal user interfaces with the Charm ecosystem. Use when Codex needs to design, implement, refactor, or extend Go CLI/TUI applications using Bubble Tea, Lip Gloss, Bubbles, Huh, Glamour, Wish, Log, Harmonica, or related Charm libraries; choose the right Charm tool; structure Bubble Tea models, messages, commands, and views; or turn a plain CLI workflow into a feature-rich terminal UI.

- Skill: `peternicholls/charm-tui-builder` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add peternicholls/charm-tui-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peternicholls/charm-tui-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: peternicholls (https://skillmd.com/u/peternicholls)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peternicholls/charm-tui-builder

---


# Charm TUI Builder

## Overview

Use this as the entry skill for Charm terminal UI work. Start by selecting the right Charm libraries, then shape the app around Bubble Tea's model/update/view loop, terminal constraints, and explicit verification.

## Workflow

1. Identify whether the user needs an inline prompt, full-screen TUI, SSH app, markdown renderer, or non-interactive CLI polish.
2. Read `references/build-patterns.md` before implementing architecture, state flow, routing, async commands, or multi-screen behavior.
3. Prefer Bubble Tea for interactive application state, Lip Gloss for layout/style, Bubbles for common components, Huh for form-like input, Glamour for markdown, Wish for SSH delivery, Log for structured logs, and Harmonica for spring motion.
4. Inspect the existing project before adding dependencies. Reuse current model, message, style, and component patterns when present.
5. Implement the smallest coherent user flow first: initial model, key map, viewport sizing, render states, error states, and quit/cancel behavior.
6. Verify with `go test ./...`, `go vet ./...` when available, and a manual terminal run at narrow, normal, and wide widths.

## Library Choice

- Use Bubble Tea when UI behavior depends on evolving state, keyboard/mouse input, async work, resize handling, or multiple views.
- Use Huh when the workflow is a bounded form or wizard and the user mostly answers fields.
- Use Bubbles when a standard component already exists: list, table, viewport, text input, text area, spinner, progress, paginator, timer, stopwatch, help, key bindings, or file picker.
- Use Lip Gloss for every non-trivial view layout. Avoid hand-padding large strings when a style, join, table, list, tree, or adaptive color can express the intent.
- Use Glamour when displaying markdown content; do not hand-roll markdown styling.
- Use Wish when users should connect over SSH, each session needs its own TUI, or SSH keys/pty dimensions are part of the product.
- Use Log for human-readable structured logs; never print debug traces into an active TUI surface.
- Use Harmonica only for motion that clarifies state change. Keep motion optional and bounded.

## Suite Routing

- Use `charm-lipgloss-layout` for visual hierarchy, style, measurement, responsive layout, tables/lists/trees, and polish.
- Use `charm-bubbletea-components` for Bubbles component selection, focus, key maps, and component update/view composition.
- Use `charm-huh-forms` for prompts, forms, dynamic fields, validation, and accessible input.
- Use `charm-glamour-markdown` for Markdown rendering, wrapping, styling, and viewport integration.
- Use `charm-wish-ssh-apps` for SSH-accessible TUIs, Wish middleware, auth, PTY, and session behavior.
- Use `charm-tui-motion-observability` for Harmonica motion and Charm Log instrumentation.
- Use `charm-tui-qa` for tests, manual terminal UX checks, screenshots, videos, VHS, and completion evidence.

## Implementation Rules

- Keep state explicit in the model. Avoid package-level mutable UI state unless the existing code already uses it deliberately.
- Treat `Update` as the only place that mutates UI state. Keep `View` pure and fast.
- Use typed messages for async results, ticks, window size, loading outcomes, and domain events.
- Return commands for I/O, timers, process execution, and async work; do not block inside `Update`.
- Track terminal width and height in the model and render every view for constrained widths.
- Provide discoverable key help and consistent escape paths: `esc`/`ctrl+c` for cancel or back, `q` only when safe and expected.
- Preserve screen reader or plain-output paths for forms and critical workflows.
- Prefer clear empty, loading, error, success, and disabled states over decorative output.

## Avoid

- Avoid writing a custom event loop when Bubble Tea should own input, rendering, and commands.
- Avoid concatenating ANSI escape sequences by hand when Lip Gloss or a Bubble component can render the view.
- Avoid layouts that only work at the developer's terminal size.
- Avoid making every key global. Scope key handling by screen and focus.
- Avoid logging to stdout/stderr while a full-screen TUI is active unless the program has a debug/log file path.
- Avoid adding Charm libraries speculatively. Each dependency should own a visible part of the UX.

## Verification

- Run unit tests for update logic and domain reducers.
- Add golden tests or snapshot-style tests for stable view output where the project already uses them.
- Run the TUI manually in at least `80x24`, a narrow width around `60` columns, and a wide width above `120` columns.
- Exercise keyboard-only navigation, cancel/back paths, loading and error states, and resize behavior.
- Use `charm-tui-qa` when the task requires screenshots, VHS recordings, visual review, or richer terminal UX checks.

## References

- `references/build-patterns.md`: architecture patterns, module paths, message design, and view-state checklist.