tui

https://github.com/user-attachments/assets/4e62e1ad-fd89-4266-b615-a0d0a344da12

Rich, interactive terminal UI components for pi agent

— defined in a small Lisp DSL, persisted to disk, and rendered as full-screen overlays on demand.

Most agent interactions collapse to text: the agent asks a question, you type an answer, and both sides guess at structure. tui replaces that back-and-forth with purpose-built input widgets. Instead of typing "option 2" in response to a numbered list, you navigate a radio picker. Instead of describing a number with a note about the valid range, you turn a rotary dial. The agent gets a typed value; you get a clear, keyboard-driven UI.

This makes tui a single replacement for question-prompt plugins, checklist plugins, checkbox plugins, and any other extension whose job is structured input — while keeping the entire widget definition inside the conversation context as a tiny Lisp source file.

---

Install

pi install npm:tui

Or for a project-local install:

pi install -l npm:tui

After install, pi loads the extension automatically. No configuration needed.

---

Use cases

Confirmation dialogs

Replace yes/no text prompts with a keyboard-navigable confirm widget. The agent defines it once and reuses it anywhere a destructive action needs approval.

Radio and checklist pickers

Replace numbered-list answers with a real picker. The agent passes a list of options; you select with arrow keys and confirm with Enter. The return value is the chosen item, not a string to parse.

Multi-step forms

Chain multiple overlays to collect structured input across several fields — filenames, environment names, feature flags — without a free-text round-trip for each one.

Progress and status displays

Render progress bars, gauges, and live-updating dashboards during long-running tasks. Timers drive re-renders without waiting for a new tool call.

Domain-specific controls

When a project has a recurring input pattern — selecting from a config enum, adjusting a numeric threshold, picking a deployment target — the agent can define a custom component for it once and save it to .pi/ui-components/. Every subsequent conversation in that project gets the control for free.

---

pi tools

Installing tui registers two tools in the pi agent.

tui_define_component

Saves a Lisp DSL module to .pi/ui-components/<name>.lisp and registers it in the runtime. The agent calls this to create or update a component definition.

{
  "source": "(defcomponent confirm (message) ...)",
  "scope": "local",
  "module": "confirm"
}

Parameter	Description
source	Full Lisp module source — one or more defcomponent / defview forms
scope	"local" (project, .pi/ui-components/) or "global" (~/.pi/agent/ui-components/). Default: "local"
module	File/module name. Inferred from the first defcomponent or defview name if omitted

Global components are available in every project. Local components are scoped to the current working directory.

tui_create_dynamic_ui

Launches a saved component by name as a full-screen overlay and returns the emitted value to the agent.

{
  "componentId": "confirm-delete-123",
  "type": "confirm",
  "title": "Confirm deletion",
  "config": { "message": "Delete production database?" }
}

Parameter	Description
type	Component name as registered by tui_define_component
config	Props object — keys map to the component's param list
title	Displayed in the overlay header
componentId	Unique identifier for this invocation

Returns the value passed to (emit ...) in the DSL, or null if the user dismisses with Escape / Ctrl+C.

Hotload: the component's source file is re-read from disk on every tui_create_dynamic_ui call. Edit a .lisp file and the next invocation picks up the change without restarting the agent.

---

Skill

Installing tui also registers the tui-runtime-components skill, which gives the agent:

• Full DSL syntax reference and layout primitives
• A component catalog with ready-to-use patterns (radio list, rotary encoder, progress gauge)
• Guidance on when to define a new component vs. reuse a saved one

The agent uses the skill automatically when writing DSL source — you do not need to instruct it.

---

Hotload

Every tui_create_dynamic_ui call re-reads the component's source file from disk before instantiation:

.pi/ui-components/
  confirm.lisp          ← edit here, runs immediately on next call
  my-picker.lisp
  rotary-encoder.lisp

The load order:

1. Look up the component name in the in-memory index
2. Re-read its .lisp file from disk and re-compile
3. If not yet registered, scan local then global directories for <name>.lisp
4. Instantiate the freshly compiled ComponentDef

This means the agent can call tui_define_component to write a new version of a component, then immediately call tui_create_dynamic_ui to run it — all within the same message.

---

Bundled components

The package ships three ready-to-use components in .pi/ui-components/:

Component	Description
radio-list	Single-select list with keyboard navigation and optional pre-selection
rotary-encoder	Numeric dial with configurable min, max, step, and initial value
progress-gauge	Animated progress display driven by a timer

The agent can use these directly or use them as templates when defining new ones.

---

Writing your own components

See docs/dsl.md for the full DSL reference — layout primitives, state, bindings, timers, control flow, and built-in functions.

---

Programmatic API

The runtime is also importable as a library for use in other pi extensions or tools:

import { compileModule, instantiate, ModuleLoader } from "tui";

See docs/api.md for the full API reference.

---

Package structure

index.ts               pi extension entry — registers tui_define_component and tui_create_dynamic_ui
src/
  parser.ts            Lisp S-expression parser
  runtime.ts           DSL evaluator, layout engine, component instantiation
  loader.ts            ModuleLoader — persistence and hotload
  runner.ts            makeUiRunner — pi-tui overlay adapter
  index.ts             Public API exports
.pi/
  skills/
    tui-runtime-components/   Skill loaded by pi agent
  ui-components/              Saved component files (created at runtime)
docs/
  dsl.md               DSL language reference
  api.md               Programmatic API reference