Textual UI Framework

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• vibe/cli/textual_ui/widgets/tool_widgets.py
• vibe/cli/textual_ui/widgets/config_app.py
• vibe/setup/onboarding/screens/theme_selection.py
• tests/autocompletion/test_ui_chat_autocompletion.py
• vibe/core/llm/format.py (Inferred from logic in vibe/core/system_prompt.py)

The Textual UI Framework provides the Terminal User Interface (TUI) for the QQcode application. It leverages the textual Python library to create a rich, interactive command-line experience. The framework manages specialized widgets for tool interaction, configuration management, and onboarding flows, ensuring that complex AI-driven operations are presented clearly to the user within a terminal environment.

Sources: CLAUDE.md, vibe/cli/textual_ui/widgets/tool_widgets.py

Architecture and Component Structure

The framework is built around the textual.app.App and textual.screen.Screen abstractions. It uses a component-based architecture where various parts of the interface (chat input, tool results, configuration menus) are encapsulated into dedicated widgets.

Widget Hierarchy and Navigation

The UI follows a structured layout comprising containers and specific interactive elements. Key components include:

• VibeApp: The main application entry point that manages the global state and routing.
• OnboardingScreen: A specialized screen sequence for first-run setup, including theme and API key configuration.
• ChatInputContainer: Handles user input, including complex features like slash commands and file autocompletion.
• Tool Widgets: Specialized displays for tool approvals and results.

Specialized Tool Widgets

To handle the interactive nature of AI tool execution, the framework implements a dual-widget system for every tool: one for Approval (pre-execution) and one for Results (post-execution).

Approval and Result Pairs

Each built-in tool has a corresponding pair of classes that inherit from ToolApprovalWidget and ToolResultWidget.

Tool Name	Approval Widget	Result Widget	Key Features
Bash	BashApprovalWidget	BashResultWidget	Displays raw bash commands in Markdown blocks.
Write File	WriteFileApprovalWidget	WriteFileResultWidget	Syntax-highlighted diffs and content previews.
Edit	EditApprovalWidget	EditResultWidget	Color-coded unified diff lines (added/removed).
Todo	TodoApprovalWidget	TodoResultWidget	Interactive status icons (☐, ☑, ☒).
Grep	GrepApprovalWidget	GrepResultWidget	Pattern matching highlighting and file path results.

Sources: vibe/cli/textual_ui/widgets/tool_widgets.py:1-250

Logic Flow for Tool Interaction

When an agent requests a tool call, the UI framework transitions through states to manage user safety and data visibility.

Configuration and Customization

The framework includes a dedicated ConfigApp widget for modifying settings in real-time and a ThemeSelectionScreen for visual customization.

Settings Management

The ConfigApp manages a SettingDefinition list which tracks key/value pairs, labels, and interaction types (e.g., "cycle").

• Provider/Model Sync: The UI contains logic to ensure that if a user changes the active_provider, the active_model list is automatically updated to reflect only models belonging to that provider.
• Theme Cycling: Users can cycle through BUILTIN_THEMES (excluding textual-ansi) and see immediate updates.

Sources: vibe/cli/textual_ui/widgets/config_app.py:50-150

Theme Selection System

During onboarding, the ThemeSelectionScreen provides a dynamic preview of the application's appearance using PREVIEW_MARKDOWN.

# theme_selection.py highlights
THEMES = sorted(k for k in BUILTIN_THEMES if k != "textual-ansi")
VISIBLE_NEIGHBORS = 3
FADE_CLASSES = ["fade-1", "fade-2", "fade-3"]

The selection UI uses a "fading" list approach where the selected theme is centered and highlighted, while neighboring themes are displayed with decreasing opacity.

Sources: vibe/setup/onboarding/screens/theme_selection.py:15-50

Interactive Input and Autocompletion

The ChatInputContainer utilizes a CompletionPopup to assist users with commands and file paths.

Autocompletion Logic

The system supports two primary triggers:

1. Slash Commands (/): Triggers a list of internal meta-commands (e.g., /config, /summarize).
2. File Mentions (@): Triggers a recursive search of the file tree to suggest relevant file paths.

Conclusion

The Textual UI Framework is the critical bridge between the user and the underlying AI agent. By providing specialized widgets for tool inspection, a robust configuration system, and intelligent autocompletion, it ensures that terminal-based coding remains efficient and safe. Its modular design allows for easy extension as new tools or configuration options are added to the QQcode core.