# Grindlemire Go Tui
> Builds, debugs, and reviews terminal UIs using github.com/grindlemire/go-tui, .gsx templates, the tui CLI, reactive State, KeyMap events, flexbox terminal layout, inline mode, and stream output. Use when creating or modifying Go TUI apps with go-tui or when the user mentions .gsx, tui generate, go-tui components, or StreamAbove.
- Skill: `cylixlee/grindlemire-go-tui` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add cylixlee/grindlemire-go-tui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cylixlee/grindlemire-go-tui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cylixlee (https://skillmd.com/u/cylixlee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cylixlee/grindlemire-go-tui
---
# Go TUI
## When to Use This Skill
Use this skill when:
- Creating, modifying, debugging, or reviewing a Go terminal UI built with `github.com/grindlemire/go-tui`.
- Working with `.gsx` files, `templ` components, generated `*_gsx.go` files, or the `tui` CLI.
- Designing component state, keyboard/mouse handling, focus, scrolling, inline widgets, or streaming output for a go-tui app.
- Diagnosing layout, rendering, event propagation, watcher, generated-code, inline, or terminal-restoration problems in a go-tui project.
Do not use this skill for Bubble Tea, tview, termui, curses, generic Go CLI work, or web frontend work unless go-tui is specifically involved.
## Mental Model
go-tui is a declarative terminal UI framework for Go with templ-like `.gsx` syntax and flexbox-style terminal layout.
```text
.gsx files -> tui generate -> *_gsx.go files -> go build -> terminal app
```
Runtime flow: event loop -> component render -> flex layout -> double-buffered diff render -> ANSI terminal output.
Components render an element tree from current state. Key handlers, mouse handlers, watchers, events, and queued updates mutate state on the app event loop. State changes mark the app dirty; the next frame re-renders.
Treat this skill as the working reference for Go TUI. Apply these patterns directly.
## Default Workflow
1. Inspect `go.mod`, `.gsx` files, generated `*_gsx.go` files, `main.go`, tests, and package layout.
2. Install dependencies only when missing: `go get github.com/grindlemire/go-tui` and `go install github.com/grindlemire/go-tui/cmd/tui@latest`.
3. Edit `.gsx` and normal `.go` files. Never hand-edit generated `*_gsx.go` files.
4. Prefer a root struct component that owns shared state and composes children.
5. Use pure `templ` components for stateless visual fragments; use struct components for state, refs, events, watchers, lifecycle, key maps, or mouse handling.
6. After GSX edits, run `tui generate ./...`.
7. Verify with `tui fmt --check ./...`, `tui check ./...`, `tui generate ./...`, `go test ./...`, and `go run .` for interactive smoke tests when feasible.
## CLI
```bash
tui generate [path...] # Generate Go code from .gsx files
tui check [path...] # Validate .gsx files without writing output
tui fmt [path...] # Format .gsx files
tui fmt --check [path...] # Check formatting without modifying
tui lsp # Start language server on stdio
```
Path forms: `./...` recursively processes all `.gsx` files, a directory processes that directory, and a file processes one source file. Generated files sit beside sources, e.g. `app.gsx` -> `app_gsx.go`.
## App Patterns
Standard interactive app:
```go
func main() {
app, err := tui.NewApp(
tui.WithRootComponent(App()),
// tui.WithMouse(),
// tui.WithFrameRate(60),
// tui.WithInlineHeight(5),
)
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
defer app.Close()
if err := app.Run(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
```
One-shot styled output without an event loop:
```go
tui.Print(View("hello"))
s := tui.Sprint(View("hello"), tui.WithPrintWidth(80))
err := tui.Fprint(w, View("hello"), tui.WithPrintWidth(120))
```
Manual loops are for integration with external event loops only. Use `app.Open()`, `app.Events()`, `app.Dispatch(ev)`, `app.Step()`, `app.Render()`, and `app.StopCh()`. If work happens on that same main loop, mutate state directly; from other goroutines, use `app.QueueUpdate`.
## GSX Syntax
`.gsx` files are Go files with `templ` declarations. They support normal packages, imports, Go expressions, `if`, `for`, local element bindings, and component calls.
Pure component:
```gsx
package main
import tui "github.com/grindlemire/go-tui"
templ Card(title string) {