Overview

The 8gent TUI is built with Ink v6 (React for CLI). It provides a rich terminal experience with animations, intelligent suggestions, visual task management, and accessibility features. The design system uses semantic color tokens so the UI remains readable across terminal themes (dark, light, Solarized, etc.).

Key Screens

Chat Screen

The primary interface. You type at the bottom, messages appear above. The status bar shows the active model, git branch, and current agent mode.

Messages render with typing effects - characters appear progressively for short responses, word-by-word for longer content. Fade-in and pop-in animations smooth the visual flow.

Kanban Board

Toggle with /kanban or /k. The board has three columns: Backlog, In Progress, and Done. When 8gent creates a plan, each step becomes a Kanban card that moves automatically as the agent works.

┌─────────────────────────────────────────────────────────────────┐
│ Backlog (3)     │ In Progress (1)  │ Done (2)                  │
├─────────────────────────────────────────────────────────────────┤
│ ○ Add tests     │ ● Fix auth bug   │ ✓ Setup project           │
│ ○ Update docs   │                  │ ✓ Create components       │
│ ○ Add caching   │                  │                           │
└─────────────────────────────────────────────────────────────────┘

Navigate cards with arrow keys.

Animation Gallery

Access with /animations or /anim. 8gent includes ten ASCII animations:

Process Sidebar

Toggle with Ctrl+B. Shows background tasks running in parallel - long-running commands, dev servers, build processes. Tasks are promoted to the sidebar automatically when they exceed a time threshold.

ADHD / Bionic Reading Mode

Toggle with /adhd, /bionic, or /focus.

Bionic reading bolds the first half of each word, creating visual anchors that help your brain process text faster:

Normal:   The quick brown fox jumps over the lazy dog
Bionic:   Th·e qui·ck bro·wn fox jum·ps ov·er the la·zy dog

The bolded portions (before the dot) create fixation points. Research suggests this can improve reading speed by up to 2x for some readers.

Toggle on or off explicitly with /adhd on or /adhd off.

Ghost Suggestions

As you type, dim ghost text appears predicting your next command or input. The prediction system draws from three sources:

• Git state - If you have uncommitted changes, it may suggest a commit
• Active plan - Shows the next step from the current BMAD plan
• Command history - Learns from your recent inputs

Press Tab to accept the full suggestion. Press Esc to dismiss it.

Voice Output

8gent can speak completion summaries aloud using TTS. The default voice is Moira (Irish) on macOS. Configure voice output via the /voice command or through a hook:

{
  "type": "onComplete",
  "mode": "shell",
  "command": "say -v Moira '{result}'"
}

On macOS, this uses the built-in say command. An optional local TTS server can be configured for custom voices. Voice output is useful for long-running tasks where you have switched to another window.

Keyboard Shortcuts

Launch Splash & Music

A cinematic splash plays on every TUI launch — block-letter 8GENT wordmark, flourish, then typewriter slide-in for the title, subhead, and body line. Total runtime ~8.5 seconds, paced to a slow-starting launch instrumental that ships in the npm package at apps/tui/sounds/launch.mp3. On first run the file is auto-copied to ~/.8gent/sounds/launch.mp3 so you can swap it for your own.

Audio is fired via macOS afplay at 15% linear gain (-v 0.15) so the music sits well under any narration you layer on later. The child process is tracked at module scope and dies with the TUI on SIGINT, SIGTERM, normal exit, and uncaughtException — no orphan afplay survivors.

When the splash dismisses (any keypress OR auto-timeout), the music gradually fades out over 2.4 seconds via ffplay's afade filter (kills the original afplay, spawns a continuation that picks up at the same elapsed time with a fade-out filter). If ffplay isn't on $PATH we fall back to an abrupt cut.

Opting out:

8GENT_NO_INTRO=1 8gent     # skip the splash entirely
8GENT_LITE=1 8gent         # also skips heavies; splash skipped as a side effect

Manual stop from inside the TUI: type /quiet (aliases /mute, /shut, /silence) to kill any in-flight intro music immediately and confirm with a system message.

Custom sound: drop a file at ~/.8gent/sounds/launch.mp3 to override the bundled one. Or set an absolute path via ui.introSound in ~/.8gent/settings.json.

HUD Music Player

When a track is loaded via /dj, a one-line HUD widget renders above the status bar showing track title, progress bar, elapsed/duration, volume meter, and hotkey hints. The widget is hidden when nothing is playing. It polls dj.status() every 700ms — cheap because mpv IPC is a local socket.

Hotkeys (all Ctrl+Shift+ to avoid clashing with chat input):

Implementation lives at apps/tui/src/components/HudMusicPlayer.tsx. The structured DJ.status() snapshot it polls is exposed from packages/music/dj.ts for any UI consumer (dashboard, debugger, third-party shells).

Message Components

The TUI uses a layered component system for rendering messages:

• FadeIn - Smooth opacity transitions for new messages
• PopIn - Scale-up entrance effects for badges and alerts
• TypingText - Character-by-character reveal for short responses
• WordByWord - Word-level streaming for long content
• GlowText - Pulsing highlight effect for important information

Processing Indicators

• AnimatedSpinner - Multiple styles: dots, line, arc, bounce
• StepIndicator - Multi-step progress showing Plan, Tools, Execute phases
• WaveProgress - Animated sine wave progress bar for long operations

Design System

The TUI follows a design-system-first architecture. All UI is built from primitive components rather than raw Ink <Text> and <Box> elements.

Key primitives:

This architecture lives at apps/tui/src/components/primitives/ and apps/tui/src/theme/.