TUI

TUI는 Hermes의 modern front-end입니다. Classic CLI와 같은 Python runtime 위에서 동작하는 terminal UI입니다. 같은 agent, 같은 sessions, 같은 slash commands를 사용하지만, 상호작용 surface가 더 깔끔하고 반응성이 좋습니다.

Hermes를 interactive하게 쓸 때 권장하는 방식입니다.

실행

# TUI 실행
hermes --tui

# 최신 TUI session 재개(없으면 최신 classic session으로 fallback)
hermes --tui -c
hermes --tui --continue

# ID 또는 title로 특정 session 재개
hermes --tui -r 20260409_000000_aa11bb
hermes --tui --resume "my t0p session"

# source 직접 실행. prebuild step을 건너뜀(TUI contributor용)
hermes --tui --dev

환경변수로도 활성화할 수 있습니다.

export HERMES_TUI=1
hermes          # 이제 TUI 사용
hermes chat     # 동일

classic CLI는 계속 기본값으로 제공됩니다. CLI Interface에 문서화된 slash commands, quick commands, skill preloading, personalities, multi-line input, interrupts는 TUI에서도 동일하게 동작합니다.

TUI를 쓰는 이유

• Instant first frame - app loading이 끝나기 전 banner가 먼저 그려져, 시작 중 terminal이 멈춘 것처럼 느껴지지 않습니다.
• Non-blocking input - session 준비 전에도 message를 입력하고 queue할 수 있습니다. agent가 online이 되는 순간 첫 prompt가 전송됩니다.
• Rich overlays - model picker, session picker, approval prompt, clarification prompt가 inline flow가 아니라 modal panel로 표시됩니다.
• Live session panel - tools와 skills가 initialize되는 대로 점진적으로 채워집니다.
• Mouse-friendly selection - SGR inverse 대신 uniform background로 drag highlight를 제공합니다. 복사는 terminal의 일반 copy gesture를 사용합니다.
• Alternate-screen rendering - differential updates를 사용해 streaming 중 flicker가 없고, 종료 후 scrollback clutter가 남지 않습니다.
• Composer affordances - 긴 snippet paste-collapse, Cmd+V / Ctrl+V text paste와 clipboard-image fallback, bracketed-paste safety, image/file-path attachment normalization을 제공합니다.

같은 skins와 personalities가 적용됩니다. /skin ares, /personality pirate로 session 중에도 바꿀 수 있고 UI가 즉시 다시 그려집니다. customizable keys 전체와 classic/TUI 적용 범위는 Skins & Themes를 참고하세요. TUI는 banner palette, UI colors, prompt glyph/color, session display, completion menu, selection bg, tool_prefix, help_header를 반영합니다.

Requirements

• Node.js 20 이상 - TUI는 Python CLI가 launch하는 subprocess로 실행됩니다. hermes doctor가 이를 확인합니다.
• TTY - classic CLI와 마찬가지로 stdin pipe 또는 non-interactive environment에서는 single-query mode로 fallback합니다.

첫 실행 시 Hermes는 TUI의 Node dependencies를 ui-tui/node_modules에 설치합니다. 한 번만 몇 초 걸리며, 이후 실행은 빠릅니다. 새 Hermes version을 pull하면 source가 dist보다 새로울 때 TUI bundle이 자동 rebuild됩니다.

External prebuild

prebuilt bundle을 제공하는 distribution(Nix, system package 등)은 Hermes가 그 bundle을 사용하도록 지정할 수 있습니다.

export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
hermes --tui

해당 directory에는 dist/entry.js가 있어야 합니다.

Keybindings

keybindings는 Classic CLI와 동일합니다. 차이가 있는 동작은 다음뿐입니다.

• Mouse drag는 uniform selection background로 text를 highlight합니다.
• **Cmd+V / Ctrl+V**는 먼저 일반 text paste를 시도하고, 그 다음 OSC52/native clipboard read, 마지막으로 clipboard나 pasted payload가 image로 resolve될 때 image attach로 fallback합니다.
• **/terminal-setup**은 macOS에서 더 나은 Cmd+Enter, undo/redo parity를 위해 VS Code / Cursor / Windsurf terminal bindings를 설치합니다.
• Slash autocompletion은 inline dropdown 대신 description이 포함된 floating panel로 열립니다.
• **Ctrl+X**는 queued message(agent가 아직 running일 때 보낸 message)가 highlight되어 있으면 queue에서 삭제합니다. **Esc**는 삭제하지 않고 editing을 취소하며 highlight만 해제합니다.
• **Ctrl+G / Ctrl+X Ctrl+E**는 현재 input buffer를 $EDITOR에서 열어 multi-line 또는 긴 prompt를 작성하게 합니다. 저장 후 종료하면 prompt로 돌아옵니다.

Slash commands

모든 slash command는 변경 없이 동작합니다. 일부는 TUI가 소유해 richer output을 표시하거나 inline panel 대신 overlay로 렌더링합니다.

Command	TUI behavior
/help	category별 commands overlay. arrow key로 탐색
/sessions	modal session picker. preview, title, token totals, inline resume 제공
/model	provider별로 group된 modal model picker. cost hint 포함
/skin	live preview. browsing 중 theme 변경 적용
/details	verbose tool-call details 전환(global 또는 per-section)
/usage	rich token / cost / context panel
/agents (alias /tasks)	observability overlay. live subagent tree, kill/pause controls, branch별 cost/token/file rollups, turn-by-turn history
/reload	running TUI process에 ~/.hermes/.env를 다시 읽게 해 새 API key가 restart 없이 적용되도록 함
/mouse	runtime에 mouse tracking on/off 전환. config.yaml의 display.mouse_tracking에도 저장

다른 모든 slash command(installed skills, quick commands, personality toggles 포함)는 classic CLI와 동일하게 동작합니다. Slash Commands Reference를 참고하세요.

LaTeX math rendering

TUI의 markdown pipeline은 LaTeX math를 inline으로 렌더링합니다. $E = mc^2$와 $$\frac{a}{b}$$가 raw TeX source 대신 Unicode-formatted math로 표시됩니다. inline과 block math 모두 동작하며, 지원하지 않는 syntax는 copy 가능하도록 literal TeX를 code span으로 감싸 표시합니다.

항상 켜져 있으며 별도 설정은 없습니다. classic CLI는 raw TeX를 유지합니다.

Light-terminal detection

TUI는 light terminal을 자동 감지하고 light theme로 전환합니다. 감지는 세 layer로 이루어집니다.

1. HERMES_TUI_THEME env var - 최우선. 값: light, dark, 또는 raw 6-char background hex(예: ffffff, 1a1a2e).
2. COLORFGBG env var - xterm 계열 terminal이 쓰는 classic background color hint.
3. OSC 11 terminal background probe - COLORFGBG를 설정하지 않는 modern terminal(Ghostty, Warp, iTerm2, WezTerm, Kitty)에서 동작합니다.

terminal과 관계없이 항상 light theme를 쓰려면:

export HERMES_TUI_THEME=light

Busy indicator styles

status bar의 busy indicator는 pluggable입니다. 기본값은 agent 작업 중 2.5초마다 Hermes face palette를 회전합니다. config 또는 /indicator slash command로 다른 style을 선택할 수 있습니다.

display:
  tui_status_indicator: kaomoji   # kaomoji | emoji | unicode | ascii

session 안에서는 /indicator emoji처럼 사용할 수 있습니다. styles는 glyph width가 맞춰져 있어 rotation 중 status bar 나머지가 흔들리지 않습니다.

Auto-resume

기본적으로 hermes --tui는 실행할 때마다 새 session을 시작합니다. terminal이나 SSH connection이 예기치 않게 끊겼을 때 가장 최근 TUI session에 자동으로 다시 붙고 싶다면 opt in하세요.

export HERMES_TUI_RESUME=1          # most-recent TUI session
# 또는:
export HERMES_TUI_RESUME=<session-id>   # specific session

환경변수를 unset하거나 launch 때 --resume <id>를 명시하면 해당 실행에서 override할 수 있습니다.

Status line

TUI status line은 agent state를 실시간으로 추적합니다.

Status	Meaning
starting agent	Session ID는 live이고 tools/skills가 아직 준비 중입니다. 입력할 수 있으며 message는 queue되어 준비되면 전송됩니다.
ready	Agent가 idle 상태이며 input을 받습니다.
thinking / running	Agent가 reasoning 중이거나 tool을 실행 중입니다.
interrupted	현재 turn이 취소되었습니다. Enter를 눌러 다시 보낼 수 있습니다.
forging session / resuming	초기 연결 또는 --resume handshake 중입니다.

skin별 status bar colors와 thresholds는 classic CLI와 공유됩니다. customization은 Skins를 참고하세요.

status line은 다음도 표시합니다.

• Working directory with git branch - 예: ~/projects/hermes-agent (docs/two-week-gap-sweep). branch suffix는 side terminal에서 git checkout을 하면 mtime cache를 통해 갱신되어, launch 시점이 아니라 실제 active branch를 반영합니다.
• Per-prompt elapsed time - turn이 실행 중이면 12s/3m 45s처럼 표시되고, turn이 끝나면 32s / 3m 45s처럼 고정됩니다. 첫 숫자는 마지막 user message 이후 시간, 두 번째는 전체 session duration입니다. 새 prompt마다 reset됩니다.

Configuration

TUI는 standard Hermes config를 모두 존중합니다. ~/.hermes/config.yaml, profiles, personalities, skins, quick commands, credential pools, memory providers, tool/skill enablement가 그대로 적용됩니다. TUI 전용 config file은 없습니다.

TUI surface만 조정하는 key 몇 가지가 있습니다.

display:
  skin: default              # built-in 또는 custom skin
  personality: helpful
  details_mode: collapsed    # hidden | collapsed | expanded - global accordion default
  sections:                  # optional: per-section overrides(any subset)
    thinking: expanded       # always open
    tools: expanded          # always open
    activity: collapsed      # activity panel을 다시 표시(hidden이 기본)
  mouse_tracking: true       # terminal의 mouse reporting과 충돌하면 disable

Runtime toggles:

• /details [hidden|collapsed|expanded|cycle] - global mode 설정
• /details <section> [hidden|collapsed|expanded|reset] - 한 section override sections: thinking, tools, subagents, activity

Default visibility

TUI는 turn을 chevron만 잔뜩 있는 벽처럼 보이지 않게 하고, live transcript처럼 흐르게 하려고 section별 기본값을 다르게 둡니다.

• thinking - expanded. model이 reasoning을 emit하는 대로 inline stream합니다.
• tools - expanded. tool calls와 results가 열린 상태로 렌더링됩니다.
• subagents - global details_mode를 따릅니다. 기본적으로 collapsed이며, delegation이 실제로 발생하기 전에는 조용합니다.
• activity - hidden. gateway hints, terminal-parity nudges, background notifications 같은 ambient meta는 대부분의 일상 사용에서 noise입니다. tool failure는 실패한 tool row에 inline으로 표시되고, 모든 panel이 hidden인 경우 ambient errors/warnings는 floating alert backstop으로 표시됩니다.

per-section override는 section default와 global details_mode보다 우선합니다. layout을 바꾸려면:

• display.sections.thinking: collapsed - thinking을 다시 chevron 아래로 접기
• display.sections.tools: collapsed - tool calls를 다시 chevron 아래로 접기
• display.sections.activity: collapsed - activity panel 다시 표시
• runtime에서 /details <section> <mode>

display.sections에 명시된 값은 defaults보다 우선하므로 기존 config도 그대로 동작합니다.

Sessions

Sessions는 TUI와 classic CLI가 공유합니다. 둘 다 같은 ~/.hermes/state.db에 기록합니다. 한쪽에서 시작한 session을 다른 쪽에서 resume할 수 있습니다. session picker는 두 source의 session을 모두 보여주고 source tag를 붙입니다.

lifecycle, search, compression, export는 Sessions를 참고하세요.

Classic CLI로 되돌리기

--tui 없이 hermes를 실행하면 classic CLI를 사용합니다. 특정 machine에서 TUI를 기본값으로 쓰려면 shell profile에 HERMES_TUI=1을 설정하세요. 되돌리려면 unset하면 됩니다.

TUI가 launch되지 못하는 경우(Node 없음, bundle 누락, TTY 문제 등) Hermes는 diagnostic을 출력하고 fallback합니다. 사용자가 막히지 않도록 classic CLI로 돌아갑니다.

See also

• CLI Interface - 공유 slash command와 keybinding reference
• Sessions - resume, branch, history
• Skins & Themes - banner, status bar, overlays theme
• Voice Mode - 두 interface 모두에서 동작
• Configuration - 모든 config keys