textual-tui

Original：🇺🇸 English

Translated

12 scripts

Build, refactor, debug, test, and package Python terminal user interfaces with Textual. Use when the user wants a TUI, terminal dashboard, admin console, multi-screen workflow, keyboard-first tool, data explorer, file browser, markdown or log viewer, editor, command palette, browser-served console app, or a migration from curses/Rich-only UI to Textual—even if they never say “Textual”. Covers TCSS and themes, built-in widgets, screens and modes, reactive state, workers, browser delivery APIs, and pytest Pilot or snapshot testing.

5installs

Sourcetristanmanchester/agent-skills

Added on2026-05-12

NPX Install

npx skill4agent add tristanmanchester/agent-skills textual-tui

SKILL.md Content

View Translation Comparison →

Use this skill when the task is fundamentally about building or changing a Textual app, not merely printing Rich output or writing a non-interactive CLI.

Start by classifying the app

Pick the closest shape before writing code:

Single-screen shell
One main view with panels, tables, forms, or logs. Prefer containers plus built-in widgets.
Multi-screen workflow
Large context changes, separate flows, or drill-down views. Prefer
```
Screen
```
/
```
ModalScreen
```
.
Multi-mode admin app
Persistent top-level areas such as “dashboard / jobs / settings / logs”. Prefer named
```
MODES
```
, screen stacks, and command palette support.
Data explorer
Records plus details, filters, or side panes. Prefer
```
DataTable
```
, details panel, responsive breakpoints, and keyboard navigation.
Document or filesystem tool
Prefer
```
DirectoryTree
```
,
```
MarkdownViewer
```
,
```
TextArea
```
,
```
Tree
```
, and delivery APIs for export/download.
Chat / streaming / long-running task UI
Prefer a scrollable transcript or log plus
```
@work
```
/ workers for background operations.

If the user has not chosen an architecture, choose one and proceed.

Default engineering stance

Prefer built-in widgets first. Only hand-roll behaviour when a built-in widget clearly does not fit.
Keep the App
thin. Move screen-specific logic into
```
Screen
```
classes and reusable composite widgets.
Prefer .tcss
files over inline
```
CSS
```
once styling grows beyond a toy example.
Use IDs and semantic classes deliberately so styling and Pilot tests stay stable.
Design for narrow terminals first, then add split panes and breakpoint-driven layouts.
Leave behind tests whenever behaviour changes.

Choose the right Textual primitive

Use Screen
when navigation changes the user’s working context.
Use ModalScreen
for short interruptions: confirmations, pickers, destructive actions.
Use ContentSwitcher
for wizard steps or one-screen subflows.
Use named
MODES
when the app has durable top-level areas with separate navigation stacks.
Use command palette providers when there are many actions, bindings, or discoverability matters.
Use workers for network, subprocess, parsing, search, sleeps, or anything that may block input.

See:

Architecture decision tree
Screens, modes, and command palette

Widget-first selection rules

Before inventing custom widgets, check the widget atlas.

Common defaults:

```
DataTable
```
for record-heavy views
```
DirectoryTree
```
for filesystem navigation
```
MarkdownViewer
```
for rich document views
```
TextArea
```
for editing
```
TabbedContent
```
for grouped settings or alternate panes
```
Log
```
/
```
RichLog
```
for live output

SelectionList

,

OptionList

,

ListView

,

Tree

,

Select

,

Switch

,

Input

,

Button

for most interaction needs

Reactivity and workers

Use the playbook in reactivity and workers.

Core rules:

Put fast derived state in
```
compute_*
```
, but keep it cheap and side-effect free.
Use
```
watch_*
```
for UI reactions, not blocking work.
Use
```
var
```
when you want state without automatic refresh machinery.
Use
```
set_reactive
```
before mount when initial state changes should not trip watchers early.
Move blocking work into
```
@work
```
or
```
run_worker(...)
```
.
Use
```
exclusive=True
```
for stale-search cancellation and similar “latest request wins” flows.
For thread workers, update the UI via messages or
```
call_from_thread
```
.

Browser, dev loop, and delivery

Textual may run in a terminal or be served to a browser. Build with both in mind when relevant.

Use
```
textual run --dev
```
while iterating.
Use
```
textual console
```
and devtools when behaviour is unclear.
Use
```
textual serve
```
when browser parity matters.
Prefer
```
deliver_text
```
,
```
deliver_binary
```
, or
```
deliver_screenshot
```
for browser-friendly exports and downloads.
Use
```
open_url
```
when handing off to the user’s browser is appropriate.

See:

Browser and delivery guide
Packaging and CI

Testing is part of the feature

Default output after any non-trivial change:

one smoke test with
```
run_test()
```
one behaviour test for the changed flow
one narrow-terminal or alternate-size test when layout matters
one snapshot test when the view structure matters visually

See testing matrix.

When working on an existing project

Start with the scripts, then refine by hand:

python scripts/inspect_textual_project.py <project>

python scripts/audit_textual_project.py <project>

Generate scaffolds or tests only after you understand the existing structure.

Use the audit to catch:

oversized
```
App
```
classes
blocking handlers
missing breakpoints
missed built-in widget opportunities
missing command palette or delivery APIs
missing Pilot tests

Bundled scripts

```
scripts/scaffold_textual_app.py
```
Generate starter apps, TCSS, tests, optional
```
pyproject.toml
```
, and CI workflow.
```
scripts/inspect_textual_project.py
```
Inventory app classes, screens, widgets, bindings, IDs, workers, and styling.
```
scripts/audit_textual_project.py
```
Heuristic architecture/performance/test audit for an existing Textual project.
```
scripts/generate_pilot_tests.py
```
Emit starter smoke and behaviour tests for an existing app.
```
scripts/dump_dom_and_bindings.py
```
If Textual is installed, launch an app under
```
run_test()
```
and dump DOM and active bindings.

scripts/emit_textual_pyproject.py

Generate a packageable Hatch-based

pyproject.toml

.

```
scripts/emit_github_actions_ci.py
```
Generate a GitHub Actions workflow for Textual tests.

scripts/build_upstream_pattern_atlas.py

Summarise a local Textual repo snapshot into

references/repo-map.md

and

references/upstream-pattern-atlas.md

.

```
scripts/self_check.py
```
Compile scripts and scaffold all bundled templates as a package validation step.

Bundled starter templates

Available scaffolds:

```
dashboard
```
```
form
```
```
chat
```
```
data-explorer
```
```
file-browser
```
```
settings
```
```
wizard
```
```
log-monitor
```
```
editor
```
```
admin-modes
```
```
download-demo
```

List them with:

bash

python scripts/scaffold_textual_app.py --list-templates

Generate one with: