Labsco
msmps logo

opentui

★ 220

by msmps · part of msmps/opentui-skill

OpenTUI skill for building terminal user interfaces with the Core, React, or Solid APIs. Use for any TUI task including components, layout, keyboard and keymap handling, animations, and testing.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#analytics#scraping#voice#cloud#git

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

OpenTUI Platform Skill

Consolidated skill for building terminal user interfaces with OpenTUI. Use decision trees below to find the right framework and components, then load detailed references.

Critical Rules

Follow these rules in all OpenTUI code:

  1. Use create-tui for new projects. See framework REFERENCE.md quick starts.
  2. create-tui options must come before arguments. bunx create-tui -t react my-app works, bunx create-tui my-app -t react does NOT.
  3. Never call process.exit() directly. Use renderer.destroy() (see core/gotchas.md).
  4. Text styling requires nested tags in React/Solid. Use modifier elements, not props (see components/text-display.md).

Quick Decision Trees

"Which framework should I use?"

Which framework?
├─ I want full control, maximum performance, no framework overhead
│  └─ core/ (imperative API)
├─ I know React, want familiar component patterns
│  └─ react/ (React reconciler)
├─ I want fine-grained reactivity, optimal re-renders
│  └─ solid/ (Solid reconciler)
└─ I'm building a library/framework on top of OpenTUI
   └─ core/ (imperative API)

"I need to display content"

Display content?
├─ Plain or styled text -> components/text-display.md
├─ Container with borders/background -> components/containers.md
├─ Scrollable content area -> components/containers.md (scrollbox)
├─ Standalone scrollbar -> components/containers.md (scrollbar)
├─ ASCII art banner/title -> components/text-display.md (ascii-font)
├─ PNG/JPEG/WebP/GIF image -> components/text-display.md (image)
├─ First-draw diagnostic -> components/text-display.md (time-to-first-draw)
├─ QR code -> components/text-display.md (qr-code, @opentui/qrcode)
├─ Embedded child terminal/VT output -> components/containers.md (Core only)
├─ Data table with borders/wrapping -> components/code-diff.md (TextTable)
├─ Code with syntax highlighting -> components/code-diff.md
├─ Diff viewer (unified/split, hunk nav) -> components/code-diff.md
├─ Line numbers with diagnostics -> components/code-diff.md
└─ Markdown content (streaming) -> components/code-diff.md (markdown)

"I need user input"

User input?
├─ Single-line text field -> components/inputs.md (input)
├─ Multi-line text editor -> components/inputs.md (textarea)
├─ Select from a list (vertical) -> components/inputs.md (select)
├─ Tab-based selection (horizontal) -> components/inputs.md (tab-select)
├─ Value slider -> components/inputs.md (slider)
├─ Declarative/layered keybindings -> keymap/REFERENCE.md (@opentui/keymap)
└─ Custom keyboard shortcuts -> keyboard/REFERENCE.md

"I need layout/positioning"

Layout?
├─ Flexbox-style layouts (row, column, wrap) -> layout/REFERENCE.md
├─ Absolute positioning -> layout/patterns.md
├─ Responsive to terminal size -> layout/patterns.md
├─ Centering content -> layout/patterns.md
└─ Complex nested layouts -> layout/patterns.md

"I need animations"

Animations?
├─ Timeline-based animations -> animation/REFERENCE.md
├─ Easing functions -> animation/REFERENCE.md
├─ Property transitions -> animation/REFERENCE.md
└─ Looping animations -> animation/REFERENCE.md

"I need to handle input"

Input handling?
├─ Keyboard events (keypress, release) -> keyboard/REFERENCE.md
├─ Layered bindings, commands, leader keys -> keymap/REFERENCE.md
├─ Focus management -> keyboard/REFERENCE.md
├─ Paste events -> keyboard/REFERENCE.md
├─ Mouse events -> components/containers.md
├─ Text selection & copy-on-select -> keyboard/REFERENCE.md (selection)
└─ Host/terminal clipboard service or OSC 52 -> keyboard/REFERENCE.md (clipboard)

"I need to test my TUI"

Testing?
├─ Snapshot testing -> testing/REFERENCE.md
├─ Interaction testing -> testing/REFERENCE.md
├─ Test renderer setup -> testing/REFERENCE.md
└─ Debugging tests -> testing/REFERENCE.md

"I need platform capabilities (audio, images, clipboard, notifications, SSH)"

Platform capability?
├─ Play loaded sound or MP3/FLAC stream -> core/api.md (Audio)
├─ Capture microphone PCM / record WAV -> core/api.md (Audio)
├─ Decode, transform, or display images -> components/text-display.md (image)
├─ Read/write host or terminal clipboard -> keyboard/REFERENCE.md (clipboard)
├─ Desktop notifications (OSC 9/777/99) -> core/api.md (triggerNotification)
├─ Custom stdin/stdout (PTY, xterm.js) -> core/api.md (createCliRenderer)
└─ Serve a TUI over SSH -> core/REFERENCE.md (@opentui/ssh)

"I need to debug/troubleshoot"

Troubleshooting?
├─ Runtime errors, crashes -> <framework>/gotchas.md
├─ Layout issues -> layout/REFERENCE.md + layout/patterns.md
├─ Input/focus issues -> keyboard/REFERENCE.md
└─ Repro + regression tests -> testing/REFERENCE.md

Troubleshooting Index

  • Terminal cleanup, crashes -> core/gotchas.md
  • Text styling not applying -> components/text-display.md
  • Input focus/shortcuts -> keyboard/REFERENCE.md
  • Layout misalignment -> layout/REFERENCE.md
  • Flaky snapshots -> testing/REFERENCE.md

For component naming differences and text modifiers, see components/REFERENCE.md.

Product Index

Frameworks

FrameworkEntry FileDescription
Core./references/core/REFERENCE.mdImperative API, all primitives
React./references/react/REFERENCE.mdReact reconciler for declarative TUI
Solid./references/solid/REFERENCE.mdSolidJS reconciler for declarative TUI

Cross-Cutting Concepts

ConceptEntry FileDescription
Layout./references/layout/REFERENCE.mdYoga/Flexbox layout system
Components./references/components/REFERENCE.mdComponent reference by category
Keyboard./references/keyboard/REFERENCE.mdLow-level keyboard input handling
Keymap./references/keymap/REFERENCE.mdDeclarative layered keybindings (@opentui/keymap)
Animation./references/animation/REFERENCE.mdTimeline-based animations
Testing./references/testing/REFERENCE.mdTest renderer and snapshots

Component Categories

CategoryEntry FileComponents
Text & Display./references/components/text-display.mdtext, ascii-font, image, time-to-first-draw, styled text, qr-code
Containers./references/components/containers.mdbox, scrollbox, scrollbar, embedded-terminal, borders
Inputs./references/components/inputs.mdinput, textarea, select, tab-select, slider
Code & Diff./references/components/code-diff.mdcode, line-number, diff, markdown, text-table

Additional Packages

PackageDescriptionDocs
@opentui/keymapLayered keybinding/command engine (Bun or Node, no FFI)./references/keymap/REFERENCE.md
@opentui/qrcodeQR code component./references/components/text-display.md
@opentui/sshServe a TUI over SSH./references/core/REFERENCE.md
@opentui/threeThree.js WebGPU renderer (formerly core/src/3d)upstream packages/three
@opentui/examplesRunnable examples (formerly core/src/examples)upstream packages/examples

Core also ships loaded/streaming/captured Audio, native images, host and terminal clipboard services, and OSC desktop notifications.

Resources

Repository: https://github.com/anomalyco/opentui Core Docs: https://github.com/anomalyco/opentui/tree/main/packages/core/docs Examples: https://github.com/anomalyco/opentui/tree/main/packages/examples/src Awesome List: https://github.com/msmps/awesome-opentui