Ink-based Terminal UI (TUI)
Relevant source files
The following files were used as context for generating this wiki page:
The Ink-based Terminal UI (TUI) provides the primary interactive interface for the Hermes Agent. It uses the Ink library to render React components directly in the terminal, allowing for structured data display and real-time feedback during agent operations.
This system replaces traditional static CLI output with a dynamic, component-based view. It supports high-density information display, progress tracking, and interactive skill execution. The TUI specifically handles the visual representation of complex workflows like codebase documentation and system mapping.
Sources: ui-tui/src/app.tsx, optional-skills/software-development/code-wiki/SKILL.md:16-25
Architecture and Core Logic
The TUI architecture follows a component-driven model where the terminal serves as the rendering target. The system bridges the Gap between the Agent's backend skills and the user's terminal session.
Entry Point
The app.tsx file initializes the terminal environment. It sets up the Ink rendering loop and attaches the root App component to the terminal's standard output. This setup ensures that the UI persists and updates during asynchronous agent tasks.
Sources: ui-tui/src/app.tsx
Component Hierarchy
The UI organizes information through nested React components. The App.tsx component acts as the layout engine, managing the visibility of different skill outputs and status indicators.
The diagram shows how the TUI layers components from the entry point down to specific skill outputs.
Sources: ui-tui/packages/hermes-ink/src/ink/components/App.tsx, ui-tui/src/app.tsx
Interaction Flow
The TUI manages user input and skill execution status. When a user invokes a skill, the TUI updates its state to reflect the current stage of the operation.
Skill Execution Workflow
- The user enters a command via the terminal.
- The Agent resolves the target skill (e.g.,
code-wiki). - The TUI renders a progress indicator based on the skill's specific steps.
- The Agent reports paths and results back to the TUI.
- The TUI displays the final summary and output locations.
Sources: optional-skills/software-development/code-wiki/SKILL.md:27-40, ui-tui/packages/hermes-ink/src/ink/components/App.tsx
This sequence diagram illustrates the communication between the user, the TUI root, and the background agent skills.
Sources: optional-skills/software-development/code-wiki/SKILL.md:109-119, ui-tui/packages/hermes-ink/src/ink/components/App.tsx
Key Features and Display Components
The TUI uses specialized components to present different data types effectively. It prioritizes clarity and follows technical writing standards for all displayed text.
| Feature | Description | Implementation Target |
|---|---|---|
| Progress Reporting | Displays real-time status of multi-step processes like git clone or repo scanning. | App.tsx State |
| Path Mapping | Shows clickable or referenceable local paths for generated artifacts. | CodeWiki Module |
| Decision Logs | Renders tables of architectural decisions and open questions. | SystemAtlas Integration |
| Simple English Audit | Highlights text violations with suggested technical rewrites. | SimpleEnglish Skill |
Sources: optional-skills/software-development/code-wiki/SKILL.md:42-55, optional-skills/creative/simple-english/SKILL.md:20-30, optional-skills/creative/system-atlas/SKILL.md:38-48
UI Text Standards
The TUI enforces specific writing rules for all system-generated messages to ensure accessibility.
- It uses active voice for instructions (e.g., "Install the pump" instead of "The pump should be installed").
- It limits sentences to under 25 words in descriptive text.
- It places conditions before actions (e.g., "If the build fails, read the log").
Sources: optional-skills/creative/simple-english/SKILL.md:58-70
Skill Integration: Code Wiki Case Study
The code-wiki skill demonstrates how the TUI handles complex data. It requires the TUI to report a language breakdown and a list of documented modules.
- Scan Structure: The TUI displays the directory tree as the agent explores the codebase.
- Module Mapping: The TUI renders a table of identified modules and their purposes.
- Artifact Reporting: Upon completion, the TUI lists the paths to
README.md,architecture.md, and Mermaid diagrams.
Sources: optional-skills/software-development/code-wiki/SKILL.md:57-65, optional-skills/software-development/code-wiki/SKILL.md:121-133
Summary
The Ink-based TUI transforms the Hermes Agent into a structured, interactive environment. By leveraging React components, it provides dynamic feedback for complex technical tasks. The interface ensures that users can monitor agent progress and easily access generated documentation artifacts while maintaining high standards of technical clarity.