Dev TUI

Purpose and Scope

The Dev TUI is the local interactive surface for building and operating an eve agent before it is deployed. Running eve dev starts the local runtime and places the developer in a terminal UI where they can send chat messages, watch the agent stream, approve tool calls, and answer questions the agent asks back. This page explains what the TUI is for, how its transcript and status model work, and which setup and remote-session behaviors matter during day-to-day development.

Sources: docs/guides/dev-tui.md

Unlike a web chat demo, the Dev TUI is designed to preserve the developer ergonomics of a terminal. The transcript streams into normal terminal scrollback instead of being trapped inside a custom boxed viewport. That means the conversation remains copyable, searchable through normal terminal behavior, and visible after exit. The UI uses lightweight glyphs, compact status rows, and ephemeral panels so that agent output, tool activity, and setup prompts remain readable without hiding the actual development transcript.

The TUI also acts as the bridge between project setup and runtime inspection. On startup it displays a brand line with the agent name and a rotating tip for local sessions. If discovery found problems, the UI inserts warning and error counts between those startup lines. The same docs explain that instructions, tools, skills, and subagents are available through eve info, while /help lists the interactive commands available inside the TUI.

Relevant Source Files

• docs/guides/dev-tui.md - First-party guide for eve dev, including startup behavior, transcript rendering, status indicators, setup flows, slash-command behavior, and local-versus-remote session display rules.

Starting the TUI

Start the local development UI with eve dev. The command boots the local runtime and opens the interactive terminal session. A fresh eve init can also lead directly into this flow: according to the guide, the generated local session starts with /model prefilled so onboarding can choose a model before the first user prompt. That onboarding flow can install the Vercel CLI if needed, ask the developer to log in, and then return to /model as the first setup action.

eve dev

The initial screen is intentionally small. It prints the eve brand with the agent name, then a tip such as using /channels to add more ways to reach the agent. If the project has discovery errors or warnings, those counts appear between the brand line and the tip. This makes startup diagnostics visible without forcing the developer out of the chat flow. For deeper inspection, the guide points developers to eve info, which is the companion command for reviewing discovered agent capabilities.

The TUI runs a startup check every time. For sessions that were not launched from a fresh init flow, missing setup appears as an attention line. Individual command outcomes then hang under that line using a ⎿ connector, so setup state reads like a short action log rather than a full transcript conversation. This distinction is important: startup and command progress stay visible, but they do not pretend to be agent messages.

Reading the Transcript

The transcript is the durable record of the local interaction. It contains developer prompts, agent replies, reasoning, tool calls, nested subagent work, connection-authorization prompts, captured stdout, captured stderr, and sandbox lifecycle lines. Because it writes into normal terminal scrollback, the transcript remains useful for debugging after a session: developers can copy a tool call summary, inspect an error headline, or compare a streamed answer with the prompt that produced it.

Sources: docs/guides/dev-tui.md

Each turn renders without boxes. A colored gutter glyph marks the speaker, and tool calls collapse into a one-line summary such as ✓ get_weather city= followed by the result. Subagents render under a ◆ header and indent their work below that header, which lets delegated work remain visible without mixing it into the top-level agent voice. While the agent is waiting to answer, a green circle-dot pulses; it disappears when reasoning or answer content begins.

Errors are compact but still actionable. The guide states that docs links are highlighted, and bugs escaping the agent's own code show a dim stack trace beneath the error headline. Dev-server rebuilds are similarly compressed: only the latest rebuild row is shown, it updates in place from rebuilding to rebuilt, and paths shrink to their last two components. The result is a UI that keeps attention on the latest runtime state while leaving the actual conversation intact.

Status Lines and Remote Connections

The persistent status line summarizes session context beneath the prompt or current status. It includes the selected model, token flow for the session, the linked Vercel project, and a yellow /deploy pending marker when a channel has been added but the session still needs deployment. The Vercel segment stays hidden until the directory is linked, which prevents unlinked local projects from showing misleading deployment status.

Local and remote sessions are differentiated by their leading badge. Local sessions lead with a gray :port badge, making it clear the agent is running from the local runtime. Remote sessions lead with a padded ↗ project (environment) badge, or with the host when Vercel cannot resolve the deployment. The badge color communicates connection state: gray while checking or unavailable, yellow when authentication is required or has failed, and blue when connected.

Remote status lines omit AI Gateway endpoint state. That difference matters because the remote session is already pointed at a deployment, so the TUI emphasizes deployment identity and authentication state rather than the same local endpoint diagnostics. The status segments use · separators, preserving a compact single-line summary even when model, token flow, project, environment, and deployment markers are all present.

Slash Commands and Setup Panels

Slash commands are interactive operations inside the TUI, but they are rendered separately from the agent transcript. Each command echoes as an invocation line, asks questions through a bordered panel that temporarily takes the input area's place, and finishes with a one-line ⎿ result. The guide emphasizes one question at a time, which keeps setup flows predictable even when a command has multiple decisions or browser-based authorization steps.

Sources: docs/guides/dev-tui.md

The visible command set in the guide includes /help, /model, /channels, /deploy, /vc:install, and /vc:login. /help is the discovery point for every command available in the current TUI. /model is used by the fresh-init onboarding path to choose or configure the model. /channels is suggested as the way to add more ways to reach the agent. /deploy is tied to the pending deployment marker, and the Vercel CLI commands support install and login setup.

Loading behavior is intentionally consistent. Model, channel, connection, and Vercel CLI commands use the same green square pulse as the build phase, while /deploy keeps a spinner. If a connection setup is waiting for browser action, the pulse and the word browser turn yellow. Setup menus mark the selected option with a filled arrow and an inverse label, while text prompts use a blinking block cursor at the caret. Warning rows use yellow selection labels; normal selected labels are blue.

System-to-Code Mapping

The guide positions the Dev TUI as the runtime-facing companion to eve's filesystem-first agent model. The TUI does not author instructions, tools, skills, subagents, channels, or schedules itself; instead, it surfaces the results of discovery and local runtime execution. When discovery reports problems, startup counts show the developer that the filesystem model could not be fully loaded. When capabilities are healthy, eve info provides the structured inventory, and the TUI becomes the place to exercise those capabilities conversationally.

Tool calls and subagents are presented as runtime events rather than source files. A typed tool invocation collapses to a compact line with its name, arguments, and result. A delegated subagent run nests beneath its header. Connection authorization prompts appear in the transcript, reflecting the fact that external systems can require user consent or credentials during a turn. Sandbox lifecycle lines and captured process output also appear there, which makes the TUI useful for diagnosing both model behavior and execution environment behavior.

Practical Workflow

A typical local workflow starts by running eve dev, checking the brand line and any discovery counts, then using /model if the session needs model setup. After that, send a prompt that exercises the agent's core path and watch the transcript for streamed reasoning, tool summaries, and output. If a tool needs approval or a connection needs authorization, respond directly in the panel or browser flow indicated by the TUI. When the agent changes, rebuild status updates in place so the latest edit state remains visible.

When adding channels, watch for the yellow /deploy pending marker. That marker indicates the current local session has configuration that needs to be shipped before the channel can reach the deployed agent. When pointing the TUI at a deployment, use the remote badge color and label to verify whether the project and environment resolved, whether authentication is required, and whether the remote session is connected. For command discovery, use /help; for project capability discovery, use eve info.