Quick Run

The fastest way to see what FrankenTUI does is to run the demo showcase — a single binary that ships 46 interactive screens, each one demonstrating a specific subsystem. The showcase is also the canonical snapshot-test target, so every screen you see is what the tests see.

This page is for people who have a built workspace and want to poke at running code. If you don’t have a workspace yet, see installation first. If you want to embed the runtime in your own code, see hello-tick.

The demo showcase is the primary way to see the system — not the harness. Use the showcase for exploration; the harness is for running specific reference examples during development.

Mental model

Run the showcase

run the showcase


cargo run -p ftui-demo-showcase

Navigate with arrow keys. Press Enter to open a screen. Press q to quit. Most screens have their own keybinding hints visible at the bottom.

Pick a specific view

Set FTUI_HARNESS_VIEW to jump directly to a screen instead of starting at the menu:

pick a view


FTUI_HARNESS_VIEW=dashboard         cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=visual_effects    cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=command_palette_lab cargo run -p ftui-demo-showcase

See screen catalog for the full table of FTUI_HARNESS_VIEW values.

Harness examples

The ftui-harness crate ships reference examples — smaller programs useful for development and diagnostics:

harness examples


cargo run -p ftui-harness --example minimal
cargo run -p ftui-harness --example streaming

Use these when you want the simplest possible working program, or when you are testing a subsystem in isolation.

Environment variables

The showcase and harness honor a family of env vars. Most are also configurable via .env files that Cargo auto-loads.

Showcase / harness view selection

Variable	Example	Purpose
`FTUI_HARNESS_VIEW`	`dashboard`, `visual_effects`	Jump directly to a specific screen
`FTUI_HARNESS_SCREEN_MODE`	`inline`, `alt`	Select screen mode
`FTUI_HARNESS_UI_HEIGHT`	`12`	Rows reserved for inline-mode UI
`FTUI_HARNESS_ENABLE_MOUSE`	`true` / `false`	Enable mouse reporting
`FTUI_HARNESS_ENABLE_FOCUS`	`true` / `false`	Enable focus-reporting events
`FTUI_HARNESS_LOG_LINES`	`25`	Number of log lines to keep in view
`FTUI_HARNESS_LOG_MARKUP`	`true` / `false`	Enable markup in log lines
`FTUI_HARNESS_LOG_FILE`	`/tmp/ftui.log`	Redirect logs to file
`FTUI_HARNESS_EXIT_AFTER_MS`	`3000`	Auto-exit after N ms (0 = off)

Runtime rollout

Variable	Values	Default	Purpose
`FTUI_RUNTIME_LANE`	`legacy`, `structured`, `asupersync`	`structured`	Select execution backend
`FTUI_ROLLOUT_POLICY`	`off`, `shadow`, `enabled`	`off`	Control rollout behavior

See rollout lanes.

Deterministic E2E runs

Variable	Example	Purpose
`E2E_DETERMINISTIC`	`1`	Enable deterministic fixtures
`E2E_SEED`	`42`	PRNG seed for reproducible runs
`E2E_TIME_STEP_MS`	`100`	Virtual time step for replays

deterministic e2e


E2E_DETERMINISTIC=1 E2E_SEED=0 E2E_TIME_STEP_MS=100 ./scripts/e2e_test.sh
E2E_DETERMINISTIC=1 E2E_SEED=42 ./scripts/demo_showcase_e2e.sh

Terminal capability signals

These aren’t FrankenTUI-specific, but the capability probe reads them:

Variable	Purpose
`TERM`	Base terminal type
`COLORTERM`	`truecolor` / `24bit` for RGB support
`NO_COLOR`	Disable color entirely (any value)
`TMUX`, `ZELLIJ`, `KITTY_WINDOW_ID`	Multiplexer / emulator hints

Telemetry (opt-in)

Telemetry is off by default. Enable the telemetry feature on ftui-runtime and set OTEL env vars:

telemetry


# Requires building with --features ftui-runtime/telemetry
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
  cargo run -p ftui-demo-showcase --features telemetry

Tests, format, lint

dev loop


cargo check --workspace --all-targets
cargo test --workspace
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings

Snapshot baselines live alongside the showcase tests:

snapshot blessing


cargo test -p ftui-demo-showcase
BLESS=1 cargo test -p ftui-demo-showcase   # update baselines
cargo insta review                          # review changes

See snapshot testing.

Pitfalls

Very first build is slow. A clean workspace build can take several minutes because FrankenTUI is 850K+ lines of Rust. Incremental builds after that are fast. If you’re using rch (remote compilation helper), the first build happens on the remote fleet and is faster.

Don’t kill -9 the showcase. If you force-kill the process before TerminalSession drops, the terminal will be left in raw mode. Press Ctrl+C instead and let the RAII cleanup run. If you do get stuck, reset restores the terminal.

Inline mode inside tmux / screen. Some multiplexer versions have buggy DECSTBM implementations. FrankenTUI detects this and falls back to overlay redraw, but if you see flicker, try running the showcase in a direct terminal emulator to isolate the issue.

Where next

All 46 FTUI_HARNESS_VIEW values in one table.

Screen catalog

A 40-line minimal program walked through.

Hello, tick

How to bless, review, and commit snapshots.

Snapshot testing

Inline mode coexisting with log output.

Embedding in a CLI