tui-creator

name	tui-creator
description	Guide and engine specification for building index-based tree/subtree Terminal User Interfaces (TUIs). Use when creating indexed menu tools (e.g. 11, 1a, 23), subtree drill-downs, theme selection with color swatches, or task-executing terminal interfaces.
version	3.0.0
kind	hybrid
triggers	["create indexed TUI","build TUI script","create a TUI","build indexed menu interface","create subtree menu TUI","design indexed TUI"]
intent	system
created_at	2026-07-28T00:00:00.000Z
updated_at	2026-07-29T00:00:00.000Z
guardrails	["ALWAYS use the canonical template engine at <SKILL_PATH>/assets/tui_template.py. Do NOT write menu loops or ANSI rendering code from scratch.","ALWAYS place newly created TUI tools inside $TOOLS_PATH/<tui-name>/.","ALWAYS bind the main TUI runner script to a shell alias in workspace/.aliases.sh and document it in workspace/.alias_descriptions.","ALWAYS inform the user of the tool's path in $TOOLS_PATH/ and notify them that it can optionally be added as a git submodule to their dotfiles repo.","Do not hardcode absolute paths; use $SCRIPTS_PATH, $TOOLS_PATH, or $WORKSPACE_PATH environment variables.","Do not display monolithic single-screen menus when total options exceed clamp_threshold; clamp into top-level parent categories and subtrees.","Pass terminal input/output (stdin/stdout/stderr) cleanly when executing sub-tasks.","Always support clean exit (0) and back navigation (b or 0) in submenus."]
resources	["<SKILL_PATH>/assets/tui_template.py","<SKILL_PATH>/scripts/scaffold_tui.py","<SKILL_PATH>/references/ANIMATIONS_AND_ICONS.md","<SKILL_PATH>/references/MENU_SCHEMA.json"]
tools	["bash"]

TUI Creator

Defaults

• theme — obsidian (also dracula, nord, cyberpunk, emerald)
• clamp_threshold — 10; above this many options on one screen, clamp into parent categories and subtrees
• language — python (also bash)

Confirm these with the user at the start rather than assuming.

Output

scripts/scaffold_tui.py writes the spec and prints one line to stdout with the item count and the generated path; errors go to stderr. That path is the handle — read the generated file only if something needs checking.

✓ Generated TUI spec with 12 items at: /path/to/tool/menu.json

---

TUI Deployment & Shell Alias Standard

Whenever creating a new Indexed TUI tool:

1. Target Directory: Create a dedicated directory under $TOOLS_PATH/<tui-name>/ (e.g. $TOOLS_PATH/docker-manager/).

2. Notify User & Submodule Option: Explicitly inform the user upon creation:

   "Created new TUI at $TOOLS_PATH/<tui-name>/. If desired, you can add this folder as a Git submodule to your dotfiles repository."

3. Shell Alias Registration: Add a conditional alias block in workspace/.aliases.sh:

   if [ -d "$TOOLS_PATH/<tui-name>" ]; then
     alias <alias_name>="$TOOLS_PATH/<tui-name>/<tui-name>.sh"
   fi
   

   And document the alias in workspace/.alias_descriptions:

   <alias_name>=<Short description of the TUI tool>
   

---

Canonical Engine Foundation

Agents MUST NOT write custom menu rendering or input loops from scratch. Always use the canonical Python engine:

• Canonical Runner: