Skip to content
MindVM

mindvm-tui

mindvm-tui is the interactive terminal UI for talking to an agent you already configured. A scrolling output viewport on top, a prompt input on the bottom, and every SSE event from the agent (execute_js, tool_call, tool_result, sandbox_event, response) streams into the viewport live. It’s built on Bubble Tea and consumes the public mindvm-sdk-go, so it doubles as a worked example of SDK integration.

Use it when you want to:

  • Test an agent end-to-end without a browser.
  • Demo what an agent does without spinning up a frontend.
  • Resume a long-running session you started elsewhere.
  • Read tool traces inline as the agent runs.

For authoring agents, skills, or MCP servers — use the mindvm CLI. For chatting with them, use the TUI.

Install

Section titled “Install”
Terminal window
go install github.com/tavora-ai/mindvm-cli/cmd/mindvm-tui@latest
# or from a source checkout:
go install ./cmd/mindvm-tui

First run

Section titled “First run”
Terminal window
mindvm-tui

First run drops you into a setup screen that asks for the MindVM URL and a project-scoped API key. The key is validated against /api/sdk/project before anything is saved. On success the credentials persist to:

  • macOS: ~/Library/Application Support/mindvm/agent-tui.json
  • Linux: $XDG_CONFIG_HOME/mindvm/agent-tui.json (or ~/.config/mindvm/agent-tui.json)
  • Override: MINDVM_TUI_CONFIG=/path/to/file

After credentials, the TUI picks an agent:

  • One agent in the project → auto-select.
  • Two or more → interactive picker (filter with /).
  • Zero → error pointing you at mindvm agents versions create <agent-id> ....

The session is created bound to the agent’s active version, so persona, model, and the version’s skills_json filtering resolve automatically. No agent → no TUI, by design.

Subsequent runs

Section titled “Subsequent runs”
Terminal window
mindvm-tui                                # uses stored config
MINDVM_URL=... MINDVM_API_KEY=... mindvm-tui   # env wins (not persisted)
mindvm-tui --reset-config                 # rerun setup
mindvm-tui --agent <id-or-name>           # skip the picker
mindvm-tui --tools search,list_stores     # enable extra platform tools
mindvm-tui --session <id>                 # resume a prior server-side session

When the TUI exits (/quit, ctrl+c, or fatal error) it prints the current session ID and the exact --session invocation to resume it. Sessions live server-side and retain their full history, so resuming picks up where the conversation left off.

In the chat

Section titled “In the chat”
Key / commandEffect
enterSend the prompt
up / downBrowse prompt history; in-progress draft restored on down past newest
ctrl+cQuit (also prints resume command)
/upload <path>Upload a file as a document and reference it in the next turn
/quitQuit
/helpPrint the keybinding cheat sheet

Tool calls render inline as → <tool>(args) / ← <tool> ok. The viewport autoscrolls to follow output, but pgup / pgdn pause follow and let you scroll the history.

When you’d reach for it vs the CLI

Section titled “When you’d reach for it vs the CLI”
Want to…Use
Send one message and capture output for a scriptmindvm agents run <session-id> "<msg>" --output json
Iterate on a prompt or skill against the same agentmindvm-tui --agent <id>
Demo what an agent does in a screencastmindvm-tui (terminal recordings render beautifully)
Replay a session from a specific step with a tweaked promptmindvm studio replay <session-id> --from-step N
Resume a session whose ID you havemindvm-tui --session <id>

The CLI is for ops and scripting; the TUI is for conversation. Use both — they share configuration, so swapping between them is friction- free.

Section titled “Related”