TUI vs Classic: Choosing Your Surface

+15 Mana ✨
Hermes Quickstart(DOCUMENTATION)

Introduction

Hermes ships two terminal interfaces. The Classic mode is built on prompt_toolkit and looks like a friendly REPL. The newer TUI, invoked with --tui, is a modal interface with overlays, mouse support, and non-blocking input. Both share sessions, configuration, and slash commands, choosing between them is about ergonomics, not capability.

Key Concepts

  • Classic mode (hermes): A line-based REPL. Great over SSH and on minimal terminals.
  • TUI mode (hermes --tui): A modal, mouse-aware interface with overlays for sessions, models, and tools.
  • Surface parity: Both modes use the same agent loop, slash commands, and state.db.

Real World Context

A developer doing focused work on a local machine usually wants the TUI, overlays for switching models without leaving the conversation, mouse selection for copying responses, non-blocking input so you can type while the agent is generating. Someone working over a flaky SSH connection wants Classic, fewer redraws, friendlier to constrained terminals, and no mouse dependencies.

Deep Dive

What each mode is good at

text
Mode      Strengths                                  Trade-offs
────────  ───────────────────────────────────────    ──────────────────────
Classic   Tiny terminals, SSH, scripts                No overlays, no mouse
TUI       Mouse, overlays, non-blocking input         Heavier redraws

What is the same

Both modes share:

  • The same state.db and session history.
  • The same slash commands (/model, /personality, /skills, ...).
  • The same provider and credential configuration.
  • The same memory and context-file injection.

You can start a session in TUI, exit, then resume it in Classic, the conversation continues exactly where it stopped.

How to try both

bash
hermes               # Classic
hermes --tui         # TUI

Try a small task in each. Whichever you reach for naturally is the right default for you. You can change later, a config flag pins your preferred mode.

Common Pitfalls

  1. Forcing TUI over slow SSH, TUI is heavier on redraws. On a high-latency connection, Classic is more comfortable.
  2. Assuming TUI is newer-is-better, TUI is the recommended default for interactive work, but Classic is purpose-built for scripted and constrained environments.

Best Practices

  1. Use TUI for deep work, Classic for short tasks and scripts, They are tools, not generations.
  2. Pick one default, but know how to switch, Long-form conversations are more comfortable in TUI; one-shots and remote shells are happier in Classic.

Summary

  • Hermes offers two terminal surfaces: Classic (REPL) and TUI (modal).
  • Both share state, sessions, and commands, choice is about ergonomics.
  • TUI is recommended for interactive local work; Classic is the friend of SSH and scripts.

Code Examples

bash
# Classic mode, line REPL, friendliest over SSH and minimal terminals
hermes

# TUI mode, modal overlays, mouse selection, non-blocking input
hermes --tui

# Both modes share state, start in TUI, exit, resume in Classic, no data loss
hermes --tui
# (work for a while, then ^C)
hermes --continue
✓ Completed