UI Screens & Navigation
Relevant source files
The following files were used as context for generating this wiki page:
The M31 Autonomous (M31A) interface is a terminal-native application built using the Bubble Tea framework. It features a robust Terminal User Interface (TUI) consisting of 33 distinct screens designed to facilitate a seven-phase AI coding workflow. The UI is keyboard-centric, supporting Vim-style navigation and complex command interactions through a REPL and a dedicated command palette.
Sources: README.md:1-25, CONTRIBUTING.md:43-43, scripts/validate-release.sh:255-255
TUI Architecture and Framework
The M31A TUI is constructed using the Bubble Tea, Lip Gloss, and Glamour libraries. This architecture is single-threaded, requiring all state mutations to occur within a centralized Update() function to ensure thread safety. The system uses tea.Cmd and tea.Msg for handling asynchronous operations such as LLM streaming and file system events.
Sources: README.md:460-463, CONTRIBUTING.md:47-49
Core Components
The TUI is organized into several key components that manage state and rendering:
- AppState: The central state container managed in
internal/tui/app.go. - Screens: Each screen is a model struct implementing
View(),Update(), andInit(). - Command Palette: Accessed via
Ctrl+Pfor fuzzy-searching commands. - Narrative Engine: Converts low-level engine events into human-readable descriptions for the TUI.
Sources: CONTRIBUTING.md:104-108, README.md:204-206, README.md:310-310
Navigation and Interaction
Navigation within M31A is primarily driven by keyboard shortcuts and slash commands. The interface supports breadcrumb navigation, focus indicators, and a responsive layout that adapts to terminal resizing.
Key Navigation Bindings
| Key | Action |
|---|---|
Enter | Send message in REPL |
Ctrl+C | Cancel stream / Exit |
Ctrl+P | Open command palette |
Ctrl+X | Leader key for shortcuts (Settings, Theme, Rollback) |
Ctrl+Q | Open quick actions |
Esc | Close modals or model selectors |
Sources: README.md:330-340, scripts/verify_v1.sh:110-111
Workflow Navigation Flow
The TUI follows the progression of the seven-phase workflow engine. The following diagram illustrates how a user navigates through the primary screens during a standard task execution:
This diagram shows the sequential progression through the workflow phases and the auxiliary utility screens accessible from the main REPL.
Sources: README.md:120-130, scripts/verify_v1.sh:91-101
Key UI Screens
The REPL and Dashboard
The primary interface for M31A is the REPL (Read-Eval-Print Loop) where users input goals. The Dashboard provides a high-level overview of the workflow pipeline, showing phase progress, current goals, and an activity timeline.
Sources: README.md:307-309, scripts/verify_v1.sh:91-91
Plan and Execute Screens
- Plan Screen: Displays the implementation plan, including proposed changes (
[NEW]/[MODIFY]), open questions, and the task list. - Execute Screen: Shows real-time progress as tasks are implemented via the task runner. It visualizes the topological sort of tasks and tool execution status.
Sources: internal/engine/workflow/plan.go:13-35, scripts/verify_v1.sh:94-95
Verification and Rollback
- Verify Screen: Reports the results of build and test commands. If a failure occurs, it facilitates the "self-healing" loop.
- Rollback Browser: Allows users to view the git commit chain and perform soft or hard resets with a preview of changes.
- Diff Viewer: Provides inline syntax-highlighted git diffs.
Sources: README.md:301-306, scripts/verify_v1.sh:96-96
UI Configuration and Customization
The TUI appearance and behavior can be customized via the config.toml file.
| Configuration Key | Type | Default | Description |
|---|---|---|---|
ui.theme | string | "dark" | Base theme for the TUI |
ui.compact_mode | boolean | false | Enables a denser UI layout |
ui.animation_speed | string | "normal" | Controls the speed of TUI animations |
ui.reduced_motion | boolean | false | Disables unnecessary animations |
Sources: README.md:364-370, scripts/validate-release.sh:250-255
Technical Implementation Details
New screens are added by defining a constant in internal/tui/tuitypes/tuitypes.go and implementing the required Bubble Tea methods. The application manages 33 different screen constants to support various features like the model selector, permission modals, and first-run experience.
// Example of adding a new screen
// 1. Add Screen constant in internal/tui/tuitypes/tuitypes.go
// 2. Create model struct with Update() and View()
// 3. Register in NewApp() and switch statements
Sources: CONTRIBUTING.md:104-110, scripts/validate-release.sh:255-257
Conclusion
The UI of M31A is designed to provide complete visibility and control over the AI coding process. By utilizing a terminal-native, single-threaded architecture, it maintains high performance while offering complex features like fuzzy selectors, interactive diffs, and real-time workflow tracking without the overhead of a graphical environment.