TUI Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal User Interface (TUI) of M31 Autonomous is built using the Bubble Tea framework, adopting a strictly single-threaded Elm-style architecture. It provides a terminal-native, responsive environment consisting of 33 discrete screens for orchestrating the project's seven-phase autonomous workflow.
The architecture is designed to handle complex state management, LLM streaming, and tool execution progress visualization while maintaining a zero-telemetry, offline-capable operational model. Key components include a modular screen routing system, a responsive layout engine, and a specialized slash command registry.
Sources: README.md:16-20, internal/ui/tui/README.md:3-5, AGENTS.md:27-29
Core Architectural Design
The TUI operates on the Model-View-Update (MVU) pattern. All state mutations are centralized within the Update() function of the core Bubble Tea model. A critical constraint of this architecture is that AppState must never be mutated from an external goroutine; instead, all asynchronous updates must be piped back into the main loop via tea.Cmd and tea.Msg signals.
Sources: CONTRIBUTING.md:43-44, AGENTS.md:27-29
Component Hierarchy and Organization
The TUI codebase is organized into several functional domains to manage its complexity. While the core application logic resides in internal/ui/tui/, several sub-packages handle specialized tasks like streaming and command parsing.
| Component Group | Directory / Package | Responsibility |
|---|---|---|
| Core Model | internal/ui/tui/ | Application Init/Update/View loop, screen routing, and state management. |
| Shared Types | internal/ui/tui/tuitypes/ | Enums for screens, message types, and the WorkflowEngine interface. |
| Streaming | internal/ui/tui/streaming/ | LLM streaming pipeline and the autonomous tool-use agent loop. |
| Commands | internal/ui/tui/commands/ | Registry and handlers for slash commands (e.g., /workflow, /model). |
| Components | internal/ui/tui/components/ | Reusable UI elements (41 total) including file trees, tool cards, and task graphs. |
| Layout | internal/ui/tui/layout/ | Responsive chrome, breakpoint detection, and sidebar management. |
Sources: internal/ui/tui/README.md:7-60
Logic and Data Flow
The flow of data within the TUI starts from user input or external workflow events, which are converted into messages. These messages trigger state updates that subsequently refresh the view.
The TUI maintains a 10fps render rate to ensure performance while accommodating high-frequency updates from LLM streaming and tool execution.
Sources: internal/ui/tui/README.md:120-125, AGENTS.md:27-29
Screen Management
M31A utilizes a flat file structure for its 33 screens to avoid circular dependencies in Go. Each screen (e.g., REPL, Plan, Execute) follows a specific naming convention: *_model.go for state, *_view.go for rendering, and *_test.go for validation.
Major Workflow Screens
The TUI implements specialized interfaces for each phase of the Seven-Phase Workflow:
- ScreenREPL: The primary interface for chat and initial goal capture.
- ScreenPlan: Displays the proposed implementation plan and task list for review.
- ScreenExecute: Visualizes tool execution, parallel subagents, and task progress.
- ScreenVerify: Shows build results, test outputs, and self-healing reports.
- ScreenDashboard: Provides an overview of the current workflow pipeline and activity timeline.
Sources: internal/ui/tui/README.md:65-104, scripts/validate-release.sh:267-277
Command and Interaction System
The TUI includes a robust slash command system and keyboard-centric navigation. Commands are registered in a central registry and can trigger complex operations such as model arbitrage, session management, or git rollbacks.
Slash Command Registry
| Command | Category | Function |
|---|---|---|
/workflow | Workflow | Initiates the seven-phase autonomous flow. |
/model | AI/Model | Opens the fuzzy model selector with cost comparison. |
/rollback | Git | Accesses the commit-chain manager for soft/hard resets. |
/ledger | Persistence | Displays session metrics and cross-session learning data. |
/agent | Subagents | Spawns parallel child agents for isolated tasks. |
Sources: README.md:175-189, internal/ui/tui/README.md:22-31
User Interface Features
The TUI incorporates several advanced terminal features to improve the developer experience:
- Responsive Layout: Breakpoint detection for showing/hiding sidebars based on terminal width.
- Diff Viewer: Inline git diffs with syntax highlighting.
- Fuzzy Search: Used for model selection and file exploration.
- Accessibility: Reduced motion modes and configurable animation speeds for elements like the "starfield" or "breathing" effects.
Sources: README.md:144-159, internal/ui/tui/README.md:46-55
Integration with Internal Systems
The TUI acts as the primary coordinator between the user and the underlying autonomous systems.
The tuitypes.go file defines the WorkflowEngine interface, allowing the TUI to interact with the orchestration engine without being tightly coupled to its implementation.
Sources: internal/ui/tui/README.md:19-21, internal/ui/tui/tuitypes/tuitypes.go
Summary
The TUI Architecture of M31 Autonomous is a sophisticated implementation of the Bubble Tea framework, managing a high-concurrency autonomous workflow through a strictly single-threaded state loop. By organizing 33 screens into a flat structure and utilizing specialized sub-packages for streaming and commands, the system achieves a responsive, feature-rich terminal environment. It serves as the critical junction where complex LLM-driven tool execution is rendered into actionable, human-readable progress.