TUI Overview
Codebolt's terminal UI is powered by @codebolt/gotui. It gives you an interactive full-screen interface for chat, logs, git status, and file browsing without leaving the terminal.
Use the TUI when you want an interactive surface but you are working over SSH, in a terminal-only environment, or simply prefer a keyboard-first workflow.
How it launches
For most users, the TUI is launched by the main CLI:
codebolt
When you run codebolt with no flags, the CLI starts the server and then launches gotui, passing the server host, port, and current project path into the TUI process.
You can also start it against a specific project:
codebolt --project /path/to/project
What the TUI contains
The current TUI is organized around four top-level tabs:
| Tab | Purpose |
|---|---|
| Chat | Main conversation surface, conversation switching, context sidebars, dialogs |
| Logs | Connection status, TUI logs, and server logs |
| Git | Working tree status and recent commits |
| Files | File tree plus text preview |
This is different from the desktop app layout. The desktop app is a docked multi-panel GUI; the TUI is a tabbed terminal interface built around these four areas.
Startup behavior
On startup, the TUI:
- reads the server host and port from CLI-provided environment variables when launched through
codebolt - fetches project and default model/agent information from the running server
- connects to the server over WebSocket
- enters onboarding if login or default model/agent setup is still incomplete
Rendering model
The TUI runs in the terminal alternate screen, enables mouse support, and requests true-color rendering. It is designed for a real terminal session rather than plain line-by-line shell output.
Direct gotui execution
Most people should use codebolt, not gotui, because the CLI handles server startup and passes the right connection environment automatically.
If you run gotui directly, it can connect to an existing server:
gotui -host localhost -port 2719
The direct binary also has its own built-in defaults, which are documented in Remote Use, Direct gotui, and Requirements.