---
title: "opentui by msmps · skilld"
canonical_url: "https://skilld.dev/gh/msmps/opentui-skill"
meta:
  description: "Builds terminal user interfaces with OpenTUI using an imperative core API or React/Solid reconcilers. Covers layout, keyboard handling, animations, components, and testing… From msmps/opentui-skill."
  "og:description": "Builds terminal user interfaces with OpenTUI using an imperative core API or React/Solid reconcilers. Covers layout, keyboard handling, animations, components, and testing… From msmps/opentui-skill."
  "og:title": "opentui by msmps"
  "twitter:description": "Builds terminal user interfaces with OpenTUI using an imperative core API or React/Solid reconcilers. Covers layout, keyboard handling, animations, components, and testing… From msmps/opentui-skill."
  "twitter:title": "opentui by msmps"
---

`

[All skills](https://skilld.dev/skills)

[![msmps avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fmsmps.png%3Fsize%3D96)](https://skilld.dev/gh/msmps)

# **/opentui**

[@0d61d6d](https://github.com/msmps/opentui-skill/commit/0d61d6d89e3807528fd997c632c5745422e30cae "Your agent reads SKILL.md at commit 0d61d6d")

by [Matt Simpson](https://skilld.dev/gh/msmps)· [msmps](https://skilld.dev/gh/msmps)/ [opentui-skill](https://skilld.dev/gh/msmps/opentui-skill)·225 stars

 9

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.

- 27 files
- 239.5 KB
- Updated last month
- [GitHub](https://github.com/msmps/opentui-skill/blob/0d61d6d89e3807528fd997c632c5745422e30cae/skill/opentui/SKILL.md "View SKILL.md on GitHub")
- [No alerts](#third-party-checks "Third-party checks: No alerts · 5 checks · Risk SAFE")

## SKILL.md

9.8 KB

**≈51** tokens always: the name and description. **≈2.4k** when used: this file. **≈59k** more on demand in 26 files.

## 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`).

### How to Use This Skill

#### Reference File Structure

Framework references follow a 5-file pattern. Cross-cutting concepts are single-file guides.

Each framework in `./references/<framework>/` contains:

| File | Purpose | When to Read |
| --- | --- | --- |
| `REFERENCE.md` | Overview, when to use, quick start | **Always read first** |
| `api.md` | Runtime API, components, hooks | Writing code |
| `configuration.md` | Setup, tsconfig, bundling | Configuring a project |
| `patterns.md` | Common patterns, best practices | Implementation guidance |
| `gotchas.md` | Pitfalls, limitations, debugging | Troubleshooting |

Cross-cutting concepts in `./references/<concept>/` have `REFERENCE.md` as the entry point.

#### Reading Order

1. Start with `REFERENCE.md` for your chosen framework
2. Then read additional files relevant to your task:
   - Building components -> `api.md` + `components/<category>.md`
   - Setting up project -> `configuration.md`
   - Layout/positioning -> `layout/REFERENCE.md`
   - Keyboard/input handling -> `keyboard/REFERENCE.md`
   - Layered keybindings/commands -> `keymap/REFERENCE.md`
   - Animations -> `animation/REFERENCE.md`
   - Troubleshooting -> `gotchas.md` + `testing/REFERENCE.md`

#### Example Paths

```
./references/react/REFERENCE.md           # Start here for React
./references/react/api.md              # React components and hooks
./references/solid/configuration.md    # Solid project setup
./references/components/inputs.md      # Input, Textarea, Select docs
./references/core/gotchas.md           # Core debugging tips
```

#### Runtime Notes

OpenTUI runs on Bun and uses Zig for native builds. Read `./references/core/gotchas.md` for runtime requirements and build guidance.

### 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

| Framework | Entry File | Description |
| --- | --- | --- |
| Core | `./references/core/REFERENCE.md` | Imperative API, all primitives |
| React | `./references/react/REFERENCE.md` | React reconciler for declarative TUI |
| Solid | `./references/solid/REFERENCE.md` | SolidJS reconciler for declarative TUI |

#### Cross-Cutting Concepts

| Concept | Entry File | Description |
| --- | --- | --- |
| Layout | `./references/layout/REFERENCE.md` | Yoga/Flexbox layout system |
| Components | `./references/components/REFERENCE.md` | Component reference by category |
| Keyboard | `./references/keyboard/REFERENCE.md` | Low-level keyboard input handling |
| Keymap | `./references/keymap/REFERENCE.md` | Declarative layered keybindings (`@opentui/keymap`) |
| Animation | `./references/animation/REFERENCE.md` | Timeline-based animations |
| Testing | `./references/testing/REFERENCE.md` | Test renderer and snapshots |

#### Component Categories

| Category | Entry File | Components |
| --- | --- | --- |
| Text & Display | `./references/components/text-display.md` | text, ascii-font, image, time-to-first-draw, styled text, qr-code |
| Containers | `./references/components/containers.md` | box, scrollbox, scrollbar, embedded-terminal, borders |
| Inputs | `./references/components/inputs.md` | input, textarea, select, tab-select, slider |
| Code & Diff | `./references/components/code-diff.md` | code, line-number, diff, markdown, text-table |

#### Additional Packages

| Package | Description | Docs |
| --- | --- | --- |
| `@opentui/keymap` | Layered keybinding/command engine (Bun or Node, no FFI) | `./references/keymap/REFERENCE.md` |
| `@opentui/qrcode` | QR code component | `./references/components/text-display.md` |
| `@opentui/ssh` | Serve a TUI over SSH | `./references/core/REFERENCE.md` |
| `@opentui/three` | Three.js WebGPU renderer (formerly `core/src/3d`) | upstream `packages/three` |
| `@opentui/examples` | Runnable 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

Source: [SKILL.md on GitHub](https://github.com/msmps/opentui-skill/blob/0d61d6d89e3807528fd997c632c5745422e30cae/skill/opentui/SKILL.md)

## Third-party checks

<details>

<summary>No alerts17d5 checks · Risk SAFE</summary>



- Gen Agent Trust Hub17d

  This skill contains documentation and usage patterns for the OpenTUI framework, designed for building terminal user interfaces across Core, React, and SolidJS. The analysis confirmed that the skill provides legitimate development guidance; no malicious code, persistence mechanisms, or obfuscation were detected. Findings are limited to standard platform capabilities and recommended scaffolding tools.
- Socket17d

  No alerts
- Snyk17d

  Risk: LOW · No issues
- Runlayer7mo

  1/26 files flagged
- ZeroLeaks5mo

  Score: 93/100 · 2 sections analyzed

</details>

## Provenance

[Signed by skilld at 0d61d6d.](https://github.com/msmps/opentui-skill/commit/0d61d6d89e3807528fd997c632c5745422e30cae "0d61d6d89e3807528fd997c632c5745422e30cae") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated last month

## Capability

<details>

<summary>Other metadata</summary>



<dl>

<dt>metadata</dt>
<dd>

```
{
  "references": "core, react, solid, components, layout, keyboard, keymap, animation, testing"
}
```

</dd>

</dl></details>



## Topics

- [React](https://skilld.dev/frameworks/react "React components, hooks, state mgmt")
- [Testing](https://skilld.dev/skills/testing "Unit/integration/e2e tests, snapshots, coverage")
- terminal-ui
- tui
- solid
- components
- keyboard-input
- animations
- layout

## README badge

![README badge for msmps/opentui-skill](https://skilld.dev/b/msmps/opentui-skill?theme=light&label=0)

## What it does

Builds terminal user interfaces with OpenTUI using an imperative core API or React/Solid reconcilers. Covers layout, keyboard handling, animations, components, and testing for full-featured TUI applications.

Generated from the current SKILL.md.

## Frequently asked

<details>

<summary>Does this skill cover all three OpenTUI frameworks?</summary>



Yes. The skill consolidates the core imperative API, React reconciler, and Solid reconciler. Use the decision tree in the skill to pick the right framework for your task.

</details>

<details>

<summary>How do I start a new OpenTUI project?</summary>



Use \`create-tui\` with options before arguments: \`bunx create-tui -t react my-app\` (not \`bunx create-tui my-app -t react\`). Then read the REFERENCE.md for your chosen framework.

</details>

<details>

<summary>What runtime does OpenTUI require?</summary>



OpenTUI runs on Bun and uses Zig for native builds. See \`./references/core/gotchas.md\` for runtime requirements and build guidance.

</details>

<details>

<summary>Can I use `process.exit()` to shut down my TUI?</summary>



No. Always use \`renderer.destroy()\` instead. Calling \`process.exit()\` directly is a common pitfall covered in \`core/gotchas.md\`.

</details>

<details>

<summary>How do I apply text styling in React or Solid?</summary>



Use nested modifier elements, not props. See \`components/text-display.md\` for the correct pattern.

</details>

Generated from the current SKILL.md. These answers refresh after source changes.

## Related skills

-
-
-
-
-
-