Feature: Enhanced CLI TUI — Rich Markdown Rendering, Diff Previews, Token Tracking & Navigable Output

[teknium1]

Overview

The Hermes Agent CLI is functional and well-built with prompt_toolkit, but the terminal experience has fallen behind the state-of-the-art established by tools like Toad (unified CLI agent), Aider (git-integrated coding assistant), and Claude Code. These tools offer rich markdown streaming, syntax-highlighted diffs, token/cost tracking, and notebook-style navigable output that make the terminal feel like a first-class interface rather than a fallback from a web UI.

This issue proposes a set of targeted CLI TUI improvements that would make Hermes's terminal experience best-in-class. The research surveyed 10+ CLI agent tools and identified the most impactful features that Hermes currently lacks.

---

Research Findings

Terminal Agent UX Leaders

Toad CLI — The most polished terminal agent interface:

• High-performance markdown streaming with tables, syntax highlighting
• Advanced prompt editor with mouse/keyboard nav, cut/copy/paste, live markdown preview
• @ fuzzy file search (respects .gitignore)
• Notebook-like interactions: navigate/reuse previous conversation blocks
• ! prefix for inline shell commands
• SVG export of conversation content
• Supports 12+ agent backends in a single TUI

Aider — Best git integration:

• Git-native atomic commits for every AI change
• /undo instantly reverts last AI commit (git reset)
• Dirty work protection: prompts user to commit unstaged changes before AI begins
• /diff command to preview changes before applying
• Architect mode (plan only) vs Code mode (plan + execute)
• Real-time token/cost display per interaction
• Voice input
• Persistent chat history in .aider.chat.history.md

Claude Code — Best context management:

• /compact with configurable summary focus
• /clear to reset context
• Real-time token counter in the prompt bar
• Custom slash commands (user-defined shortcuts)
• "Document & Clear" workflow: dump context to a file, clear window, resume from file
• Hooks (PreToolUse) for deterministic guardrails
• Parallel runners on isolated git branches

Cursor Mission Control — Grid view to monitor/manage parallel agent workflows (relevant for subagent monitoring)

Key UX Patterns Missing from Hermes CLI

1. Token/cost tracking: No visibility into context window usage or API costs
2. Diff preview for file changes: The patch tool shows diffs in tool results, but they're not syntax-highlighted or easily scannable
3. Navigable output blocks: Can't scroll back to a specific code block and copy it; output scrolls linearly
4. Streaming markdown rendering: Output is displayed as plain text with ANSI styling via Rich, but doesn't render markdown tables, headers, or nested formatting during streaming
5. Color-coded content attribution: No visual distinction between user input, agent output, tool calls, and system messages beyond basic formatting
6. Context window indicator: No persistent display of how full the context window is

---

Current State in Hermes Agent

Current CLI stack (cli.py, ~1200 lines):

• prompt_toolkit for the input area (fixed bottom TUI)
• Rich console for output rendering (panels, colors, code blocks)
• FormattedTextControl for streaming output display
• FileHistory for command history
• SlashCommandCompleter for tab-completion of slash commands
• Compact mode for narrow terminals
• Multi-line input via Alt+Enter
• Clipboard image paste via Alt+V
• Tool progress display with emoji indicators and throttled repaints (0.25s)

What works well:

• The fixed input area TUI is solid and responsive
• Slash command system is extensible
• Tool progress with emoji is informative
• Banner display is attractive

What could be better:

• Output is mostly plain text with basic ANSI coloring
• No persistent status bar (token count, model, session info)
• No way to navigate back through output blocks
• Diffs from patch tool appear as plain tool results
• No cost/usage tracking visible during the session
• No distinction in output styling between "agent thinking" vs "agent speaking" vs "tool output"

---

Implementation Plan

Skill vs. Tool Classification

This should be a core codebase change to cli.py and potentially a new hermes_cli/tui.py module. It requires modifications to the terminal rendering pipeline, the streaming output handler, and the prompt_toolkit layout. Cannot be expressed as a skill.

What We'd Need

1. Status bar component (prompt_toolkit Window at top or bottom)
2. Enhanced markdown renderer (extend Rich markdown or use a streaming-aware renderer)
3. Output block tracking (index code blocks, diffs, and key outputs for navigation)
4. Token counting integration (from API response headers or tiktoken estimates)
5. Diff renderer (syntax-highlighted side-by-side or unified diff display)

Phased Rollout

Phase 1: Status Bar & Token Tracking

• Add a persistent status bar to the prompt_toolkit layout (top or bottom)
• Display: current model, token usage (used/max), session duration, session ID
• Update token counts from API response usage field after each turn
• Show context window fullness as a visual bar: [████████░░] 78%
• Add /usage command to show detailed token/cost breakdown for the session
• Color-code the bar: green (< 50%), yellow (50-80%), red (> 80%)
• Cost estimation based on model pricing (configurable rates)

Phase 2: Rich Output Rendering

• Upgrade streaming output to render markdown incrementally:
  • Headers with proper sizing/coloring
  • Tables rendered with box-drawing characters
  • Code blocks with syntax highlighting (via Rich/Pygments)
  • Inline code with distinct background
  • Lists with proper indentation
  • Block quotes with side border
• Color-coded content zones:
  • Agent prose: default color
  • Tool calls: dimmed/italic with emoji prefix (enhance current system)
  • Tool results: distinct background or border
  • System messages: yellow/amber
  • Errors: red with context
• Syntax-highlighted diff display:
  • When patch tool returns a diff, render it with green/red coloring
  • Show file path header with line numbers
  • Support unified and side-by-side diff formats (togglable)

Phase 3: Navigation & Advanced Features

• Output block indexing: assign IDs to code blocks, diffs, and key outputs
• Block navigation: keybinding (e.g., Ctrl+Up/Down) to jump between blocks
• Block copy: select a block by ID and copy to clipboard
• Session transcript viewer: /transcript command showing a navigable view of the full conversation
• Split-pane mode: show tool progress in a side panel while main output streams
• Search within output: Ctrl+F to search conversation history
• Export: /export command to save conversation as markdown, with proper formatting
• Subagent monitoring: when delegate_task is active, show a mini status panel for each subagent

---

Pros & Cons

Pros

• High-impact, low-risk improvements — mostly additive, don't break existing behavior
• Token tracking alone saves users money and reduces context overflow surprises
• Rich markdown rendering makes the CLI feel premium vs competitors
• Diff highlighting makes code review faster and more accurate
• Status bar provides always-visible situational awareness
• Phase 1 is small and self-contained — could ship quickly

Cons / Risks

• prompt_toolkit layout changes can be fragile and hard to test
• Markdown streaming renderer needs to handle partial content (mid-code-block, mid-table)
• Performance: complex rendering could slow down streaming display
• Terminal compatibility: not all terminals support the same ANSI features (mosh, tmux, SSH)
• Compact mode needs to gracefully degrade all these features
• Navigation features add keyboard shortcut conflicts to manage

---

Open Questions

• Should the status bar be at the top (like vim) or bottom (above the input, like many IDEs)?
• Should token tracking use server-reported usage (accurate but delayed) or local tiktoken estimates (immediate but approximate)?
• How do we handle terminals that don't support true color? Graceful degradation to 256-color or 16-color?
• Should block navigation be vim-style (j/k) or IDE-style (Ctrl+arrows)?
• Is Textual (Rich's TUI framework) worth considering for a more ambitious rewrite, or should we stay with prompt_toolkit and Rich?
• Should we add a "minimal mode" flag for users who prefer plain text output?

---

References

• Toad CLI — Best-in-class terminal agent UX
• Aider — Git-integrated CLI agent with token tracking and diff preview
• Claude Code — Terminal agent with context management
• Rich library — Python rich text rendering (already used in Hermes)
• Textual — TUI framework built on Rich
• prompt_toolkit docs — Current Hermes CLI framework
• Existing Hermes issue [Bug]: Blinking cursor or switching emojis causing prompt lines to flash repeatedly in terminal #464 (blinking cursor bug) — related TUI concern
• Existing Hermes code: cli.py lines 34-43 (prompt_toolkit imports), banner.py (ASCII art rendering)

[teknium1]

Related user feedback issues created from external tester report (March 2026):

• [UX]: CLI should use alternate screen (fullscreen) mode on launch #639 — CLI should use alternate screen (fullscreen) mode on launch
• [UX]: /help and /personalities output needs better formatting and spacing #640 — /help and /personalities output needs better formatting and spacing

Both relate to the overall CLI TUI polish tracked here.

[teknium1]

Closing to split into two more atomic issues:

• Feature: CLI Status Bar & Token/Cost Tracking — Persistent Context Window Visibility #683: CLI Status Bar & Token/Cost Tracking (Phase 1 of this issue — quick win, small scope)
• Feature: CLI Rich Rendering & Block Navigation — Streaming Markdown, Syntax Diffs & Output Indexing #684: CLI Rich Rendering, Diff Display & Block Navigation (Phases 2-3 — major refactor)

Rationale: Phase 1 (status bar + token tracking) is a small, self-contained layout addition to prompt_toolkit. Phases 2-3 require fundamentally changing the output model from raw stdout to a managed buffer (switching to full_screen mode, scrollable panels). These are architecturally different efforts with very different scopes.

Existing subset issues to coordinate with: #639 (alternate screen), #636 (async loading indicator), #640 (/help formatting), #641 (/new vs /reset UX), #464 (blinking cursor).