Ink Rendering Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Ink Rendering Engine is the primary UI framework for the Autohand CLI, leveraging the ink library to create interactive, component-based terminal interfaces using React. It manages the transition between standard TTY input and complex graphical displays, providing real-time updates for agent status, tool execution, and multi-step task progress.
The engine facilitates high-level UI abstractions such as the AgentUI for live reasoning loops and the SkillsBrowserUI for marketplace interactions. It is designed to be dynamically loaded at runtime to maintain binary portability while offering a rich, theme-aware terminal experience. Sources: src/ui/ink/InkRenderer.tsx:1-15, src/core/agent.ts:1685-1700
Architecture and Core Components
The rendering engine is built around a centralized controller, the InkRenderer class, which manages the lifecycle of an Ink Instance. It bridges the gap between the core AutohandAgent logic and the visual React components.
Component Hierarchy
The UI is structured into several specialized layers:
- InkRenderer: An imperative wrapper that controls the Ink instance, manages state updates, and handles pausing/resuming for external prompts.
- AgentUI: The root React component for the agent's main interface, rendering status, tool outputs, and queued instructions.
- ThemeProvider: A wrapper that ensures consistent styling and color application across all terminal components.
The following diagram illustrates the interaction between the Agent and the Rendering Engine:
This flow shows how the Agent drives UI updates through the Renderer wrapper while the Renderer manages the React component tree and terminal IO. Sources: src/ui/ink/InkRenderer.tsx:25-70, src/core/agent.ts:1690-1715
Key Classes and Methods
| Class | Method | Description |
|---|---|---|
InkRenderer | start() | Initializes the Ink render instance and attaches to stdin/stdout. |
InkRenderer | setWorking() | Toggles the spinner and manages completion statistics (elapsed time, tokens). |
InkRenderer | addToolOutputs() | Batches multiple tool results into the UI state for display. |
InkRenderer | pause() / resume() | Safely unmounts and remounts the UI to allow standard CLI prompts (like enquirer) to take control of the terminal. |
Sources: src/ui/ink/InkRenderer.tsx:47-150
Input Handling and Command Processing
The engine supports sophisticated input processing, including multi-line support and command-aware autocompletion.
Interactive Prompt Logic
Input is captured via readInstruction in src/ui/inputPrompt.ts, which manages several visual markers:
- Newline Markers: Uses
↵to represent line breaks in a single-line view, allowing up to 3 physical lines. - Mention Preview: A specialized sub-system for resolving
@file mentions and/slash commands. - Truncation: Automatically calculates display space and truncates long inputs, showing a line count indicator (e.g.,
... (8 lines)).
The sequence above details the autocompletion flow during active user input. Sources: src/ui/inputPrompt.ts:100-150, prd/command-ux-spec.md:40-60
Instruction Queuing
When the agent is busy (e.g., executing a complex implementation), the engine allows users to queue subsequent instructions. These are stored in the queuedInstructions array within the AgentUIState and processed sequentially as the agent completes current tasks. Sources: src/ui/ink/InkRenderer.tsx:185-210, src/core/agent.ts:1754-1770
Visual Output and Feedback
The engine provides detailed feedback during the "Reasoning + Acting" (ReAct) loop.
Tool Execution Feedback
Tool outputs are rendered with status icons and syntax-highlighted diffs. The ActionExecutor generates colorized diffs using chalk and theme-aware colors before the InkRenderer adds them to the display list.
- Added Lines: Rendered with a green prefix and a dim green background.
- Removed Lines: Rendered with a red prefix and a dim red background.
- Context: Displayed with line numbers and syntax highlighting for the specific file language.
Sources: src/core/actionExecutor.ts:1065-1120, src/ui/ink/InkRenderer.tsx:114-138
The Skills Browser
The SkillsBrowserUI is a specialized standalone interface within the engine that enables browsing and installing community skills. It uses a tab-based layout (featured, categories, search) and manages complex modal states for installation scopes (User vs. Project). Sources: src/ui/skillsBrowser/SkillsBrowserUI.tsx:85-150
The Skills Browser provides a structured way to navigate external skill repositories within the terminal. Sources: src/ui/skillsBrowser/SkillsBrowserUI.tsx:162-200
Summary
The Ink Rendering Engine serves as the bridge between Autohand's backend agent logic and the developer's terminal. By combining React's state management with terminal IO handling, it enables a dynamic and responsive CLI experience that includes live progress tracking, interactive browsers, and sophisticated diff viewing. Its ability to pause and resume allows it to coexist with standard CLI interaction patterns seamlessly.