KB TUI Design

Color Scheme

Portal-inspired (Valve). Blue is primary; orange is secondary.

Role Color Usage
Primary #4FC3F7 Status bar, shell prompt, assistant output
Secondary #FF7043 User input, chat you-prompt, base name
Error red Error messages
Dim gray Info lines, separators

Layout

┌─ KB Agent │ base: dogfood │ mode: shell ──────────────────┐  ← StatusBar (blue border)
│                                                            │
│  KB Agent — type a command or /help                       │  ← HistoryPane
│                                                            │
│  kb> query "what is the project?"                         │  ← command (orange)
│  KB is a local-first knowledge system…                    │  ← result (white)
│    Sources: kb-system-overview                            │
│                                                           │
│  kb> chat                                                 │
│  Chat mode — type /exit to return to shell.               │  ← info (gray)
│  you> how does hybrid search work?                        │  ← chat-you (orange)
│  kb> Hybrid search combines BM25 + vector rerank…         │  ← chat-assistant (blue)
│                                                           │
└────────────────────────────────────────────────────────────┘
┌─ kb> ──────────────────────────────────────────────────────┐  ← InputBar (blue border)
└────────────────────────────────────────────────────────────┘

In chat mode the InputBar border turns orange and the prompt becomes you>.

TUI vs One-Shot

  • kb (no args, TTY) → launches TUI
  • kb <command> [args] → one-shot CLI (non-interactive by default)

Interactive Commands

Shell input Behaviour
query "…" Runs intent, shows result inline with spinner
submit "…" Submits fact, shows confirmation
chat Switches to chat mode
use <base> Switches base, StatusBar updates
docs list Lists documents
docs view <id> Shows document content
/help Shows help text
/clear Clears history
/exit Quits (also Ctrl-C)
(in chat) /exit Returns to shell mode

Source Structure

src/tui/
  index.tsx                 # launchTui(config) — Ink render entry
  App.tsx                   # Root component, state, command dispatch
  runner.ts                 # runCommandForTui(), parseShellArgs()
  theme.ts                  # BLUE, ORANGE constants
  types.ts                  # TuiMode, HistoryEntry, EntryType
  components/
    StatusBar.tsx            # Top bar
    HistoryPane.tsx          # Scrollable output list
    HistoryEntryRow.tsx      # Single output line (type-aware coloring)
    InputBar.tsx             # Bottom prompt + TextInput
    LoadingSpinner.tsx       # ink-spinner wrapper