# BlackCat TUI Design — a super flashy AI harness in Textual Target: `blackcat tui` — a full-screen, animation-heavy terminal harness for `BlackCatBot` built with [Textual](https://textual.textualize.io/). This document covers the research behind it and specifies, for **every tool call**, exactly how it should be displayed and animated. Design motto: **everything moves, everything glows, nothing is boring.** See also: [README.md](README.md) (usage), [AGENTS.md](AGENTS.md) (agent rules), [docs/DEFINITION_OF_DONE.md](docs/DEFINITION_OF_DONE.md) (delivery checklist). --- ## Part 1 — Research: what a beautiful AI harness looks like these days Surveyed: Claude Code, OpenCode, Gemini CLI, OpenAI Codex CLI, Aider, Cursor Agent mode, Pi, plus trace viewers (Potato) and session browsers. The visual patterns that keep winning: ### 1. Tool cards, not log lines The atomic UI unit everywhere is a **card per tool call**: a one-line header (icon + tool name + target + live status) with a collapsible body. OpenCode renders built-in calls as "tidy cards: a one-line header with an icon, tool name, and target, plus a one-line result summary. Cards stay collapsed; `Ctrl+O` expands one to the full output or diff" (pi-tool-display). Results stream *into* the card while running; on completion the header flips to a green `✔ path (+12 −3)` / red `✘` summary line. ### 2. A visible status lifecycle Gemini CLI's `ToolMessage`/`ToolGroupMessage` components map every call through `pending → executing → confirming → success|failed|cancelled`, each with a color-coded glyph: spinner while executing, `?` amber while awaiting approval, `✔` green, `✘` red, `−` grey for skipped. The lifecycle is always scrutable — users never wonder "is it stuck?". ### 3. Inline diffs with red/green + syntax highlighting For every mutation, harnesses show before/after hunks inline: deleted lines red (often with full-line red background), added lines green, gutter signs (`+`/`-`/`~`), and the code itself syntax-highlighted. Codex CLI adds a session `/diff` view and expandable tool details; reviewers expect unified diffs, word-level highlights on changed lines, and a modal approve/reject overlay (`y`/`n`/`d`) for write operations. ### 4. Streaming everything, progressively disclosed Assistant text streams token-by-token into Markdown; tool output streams line by line; long outputs auto-collapse past a cap with "show N more lines". Reasoning/thinking blocks render in a dim, collapsible "thought" region. Nothing ever blocks the screen waiting for a whole response. ### 5. Chrome that orients: header, sidebar, footer - **Header bar**: app + model + provider + cwd/branch + approval-mode pill (Gemini's `AutoAcceptIndicator`: DEFAULT / AUTO_EDIT / YOLO). - **Side rail**: session/tool timeline or a file tree of touched files with dirty markers (Cursor agent window, Potato's file-tree sidebar). - **Footer/status line**: key hints plus a live status line — tokens in/out, session cost ticking up, elapsed time, current step `3/16` (Codex's configurable `/statusline`). - **Slash commands + command palette**: `/costs`, `/diff`, `/approvals`, `/help`, fuzzy-palette for every action. ### 6. Approvals as first-class UI Destructive tools pause on a glowing confirmation card: what will run, on what, with `y`/`n`/`a` (always) choices — inline, not a blocking stdin prompt. OpenCode/Claude Code use an approval *gradient* (ask → auto-edit → full-auto) surfaced in the header pill. ### 7. Session artifacts One-key access to the transcript (`save_report` JSON pretty-view), cost breakdown, and token/context gauges (context-window bar that fills and shifts green → amber → red). Resumability browsers exist as separate TUIs. **Takeaway for BlackCat:** card-per-tool with animated lifecycle, inline syntax-highlighted diffs, streaming Markdown chat, header/sidebar/footer chrome, approval cards, cost + context telemetry, command palette. Then turn every one of those up to eleven with motion. --- ## Part 2 — Research: how to achieve it with Textual Textual (Python, async-first, retained-DOM, CSS-styled, web-deployable via `textual-web`; company wound down mid-2025, Will McGugan maintains it as open source) gives us every primitive needed. Key APIs used by this design: ### Widgets (from the official gallery) | Widget | Role in BlackCat TUI | |---|---| | `Header` / `Footer` | Chrome: model/provider/cwd pill strip; key hints + live status | | `Input` / `TextArea` | Prompt box (`TextArea` for multiline + `Ctrl+J` newline) | | `Markdown` / `MarkdownViewer` | Streaming assistant replies, report viewer | | `RichLog` / `Log` | The transcript: auto-scrolling card stream | | `Static` | Card headers, labels, custom animated pieces | | `Vertical` | Every tool card (`ToolCard`): header `Static` plus body `Vertical`, collapsed by toggling body `display` | | `Tree` / `DirectoryTree` | Outline symbols, touched-files rail, evidence trees | | `DataTable` | Grep hits, repo-search hits, cost breakdown, models list | | `Sparkline` | Cost/token/confidence sparklines in header and cards | | `Digits` | Big animated session-cost + token counters | | `ProgressBar` | Convergence rounds, compaction, multi-edit step `2/7` | | `LoadingIndicator` | Pulsating dots; any widget's `loading` reactive swaps it in | | `Tabs` / `TabbedContent` / `ContentSwitcher` | Transcript / Diff / Costs / Report views | | `TextArea` | Diff viewer + code windows (read-only, soft-wrap, line numbers) | | `Pretty` | JSON result inspector | | `Rule`, `Label`, `Button` | Dividers, pills, approval `y/n/a` buttons (clickable!) | | `Select`, `OptionList`, `ListView` | Model/provider pickers, slash-command menu | | `Input` + `MaskedInput` | Prompt box, API-key entry screen | ### Motion system - `widget.animate(attr, value, duration=…, speed=…, easing=…, delay=…, on_complete=…)` and the identical `styles.animate(...)` — animate opacity, offset, height, colors, scrollbar position. - Easing: full easings.net set; default `in_out_cubic`; preview with `textual easing` (needs `textual-dev`). Flashy picks: `out_elastic` (card pop-in), `out_bounce` (success stamp), `out_expo` (fast slide), `in_out_sine` (breathing glows). - TCSS transitions (`transition: opacity .25s, border .25s;`) + `:hover` states for free micro-motion. - `reactive()` attributes + `watch_*` hooks: state changes auto-repaint; drive spinners, counters, gauges from reactives. - `@work` / `run_worker` + `Worker.StateChanged` messages: network/LLM/subprocess stay off the event loop; stream partial results via `call_from_thread` / message pump. - `App.notify()` toasts, modal `Screen`s (`push_screen`), built-in **Command Palette** (`CommandPalette`, providers returning `Hit`s), `App.register_theme()` + `Theme` variables (`$primary`, `$success`, `$warning`, `$error`, surfaces, borders, scrollbar…) with light/dark variants, `textual keys`/`textual diagnose` devtools. ### Rich renderables (usable anywhere in Textual) `Spinner` (60+ styles: `dots`, `arc`, `shark`, `earth`, `moon`, `pong`…), `Live`-style updates via reactives, `Progress` columns, `Syntax` (any lexer, line numbers, highlight ranges), `Table`, `Tree`, `Panel`, `Rule`, `Text` with per-span styles, `Emoji`. Anything Rich renders can be a Textual visual. ### Images (vision!) `textual-image` renders pixel images via Kitty TGP / sixel with half-block/unicode fallbacks (`auto` picks the best protocol) — used by fast-agent's TUI for image attachments. BlackCat's `--image` vision inputs get a real inline thumbnail strip. ### Testing `App.run_test()` + `Pilot` (key presses, clicks, workers) for headless UI tests of every card state. --- ## Part 3 — The BlackCat shell ### Layout (140×40 reference, responsive down to 80×24) ``` ┌─ Header ─────────────────────────────────────────────────────────────┐ │ ● BLACKCAT │ deepseek-flash │ 📁 ~/proj (main*) │ 🛡 AUTO-EDIT │ $/tok │ ├──────────┬───────────────────────────────────────────────┬───────────┤ │ SESSIONS │ TRANSCRIPT (RichLog, auto-scroll) │ TABS: Diff│ │ • chat 1 │ ┌ user ─────────────────────────── 10:41 ─┐ │ Costs │… │ │ • bugfix │ │ Fix the off-by-one in converge.py │ │ │ │ + new │ └────────────────────────────────────────┘ │ DIFF: │ │ │ ┌ ★ BlackCat (deepseek-flash) ▸ streaming ┐ │ converge.│ │ TOUCHED │ │ I'll take a look… **reading** the file…│ │ py │ │ ✎ conv…py│ └────────────────────────────────────────┘ │ @@ -12… │ │ ✚ new.md │ ┌ ⏳ read converge.py ── lines 1-60 ────┐ │ − buggy │ │ │ │ 12│ def f(x): … │ │ + fixed │ │ CTX ▓▓▓░ │ └────────────────────────────────────────┘ │ │ │ 62% 79k │ ┌ ✔ grep "off.by.one" ── 3 hits ────────┐ │ COSTS: │ │ $0.0042 │ │ … │ │ chat $… │ │ ⏱ 00:41 │ └────────────────────────────────────────┘ │ TOTAL $… │ ├──────────┴───────────────────────────────────────────────┴───────────┤ │ ❯ Fix it_ [⏎] │ │ stepped 3/16 · /help · ctrl+o expand · ctrl+p palette · q quit │ └──────────────────────────────────────────────────────────────────────┘ ``` - **Left rail** (`TabbedContent` or `ContentSwitcher`): Sessions list, Touched-files tree (dirty `✎`/`✚`/`✘` badges), context gauge (`ProgressBar` + %), live cost (`Digits` mini + `Sparkline`), elapsed clock. - **Center**: `RichLog` transcript — user bubbles, assistant Markdown stream, tool cards, approval cards, divider `Rule`s per turn. - **Right panel** (`TabbedContent`): Diff (accumulated session diff, `TextArea` read-only), Costs (DataTable + sparkline), Report (`Pretty` JSON of `save_report`), Models, Help. - **Bottom**: multiline `TextArea` prompt box with focus glow + one-line `Footer` status (step `3/16`, spinner state, key hints). Prompt-box parity with the CLI: `Up`/`Down` history, `Shift+Tab` newline-without-send, multiline paste as one prompt (see `run_chat`/`setup_readline`). - App starts on a **boot splash screen**: giant ASCII black cat (amber eyes blink!), gradient title reveal, "connecting…" shimmer, then slides away (`out_expo`). ### Theme — "Alley Cat" (dark-first, light variant too) Registered via `App.register_theme()`. Palette: - background `#0b0e14`, surface `#11151d`, panel `#161c27` - primary (amber) `#ffb454`, secondary (mint) `#7fd6c2`, accent (violet) `#c792ea` - success `#5de4c7`, warning `#ffca58`, error `#ff5f5f`, info `#59c2ff` - Tool-family colors: file-read cyan, file-write amber, patch violet, web-search mint, fetch sky, converge gradient amber→violet, scholar teal, repo lilac. - Typography: Nerd-Font-optional glyphs with ASCII fallbacks (`✔ ✘ ⏳ ★ ► ● ◆ ▶ ◀ ▲ ▼`). - Cat mascot reacts: eyes follow activity (idle slow-blink, streaming fast-blink, error red flash). ### Global motion language (applies to every card) | Event | Animation (Textual call) | |---|---| | Card mounts | `styles.animate("opacity", 1.0, duration=.25)` + slide `offset_y` 1→0 `out_expo` + border color sweep | | Running | Family-colored `Spinner` + animated `...` ticker; header border "breathes" (`opacity` .75↔1 loop via chained `on_complete`) | | Streams line | New `Static` line fades in (`opacity` 0→1, .15s); log auto-scrolls (`scroll_end(animate=True)`) | | Success | Spinner → `✔` with `out_bounce` scale pop; header flashes success color; card border pulses once; toast `notify("read ok · 60 lines · 12ms")` | | Failure | Card shakes (offset ±1 ×3, .06s each); border strobes error red; `✘` slams in; error tone toast | | Expand/collapse | Body `display` toggle; chevron rotates `▶`→`▼` | | Approval needed | Card border strobes amber, whole card gently throbs until answered; `y/n/a` buttons glow on hover | | Hover (mouse) | Card lifts: border brightens + background lightens via TCSS `:hover` + `transition` | | Long output | Auto-collapse past 40 lines with animated "▼ show 132 more" button; a card with unexpanded remainder never auto-collapses, so its more-button stays reachable | | Token/cost tick | `Digits` count-up animation + `Sparkline` push; header cost flashes on each billable call | ### The universal tool-card anatomy Every tool below follows this skeleton (`ToolCard(Vertical)`): ``` ┌ ⏳/✔/✘ ── ── <⏱ ms> ┐ │ BODY (streams while running, collapses on done unless rows are parked) │ └──────────────────────────────────────────────────────────────────────────────┘ ``` Header segments are reactives: `status ∈ pending|running|confirming|ok|failed|skipped`, `summary: str`, `elapsed_ms`. Colors: running = family color + spinner, `ok` = green `✔`, `failed` = red `✘`, `confirming` = amber `?`, `skipped` = grey `−`. All timings measured around `run_tool`. Render contract: every card is sealed after mount and after done, so no card may render as an empty bordered box. Header text and a status row exist from construction, so even a crashing mount cannot leave a blank box; the status row hides the moment real rows show. A periodic transcript audit re-seals any card that still violates the contract. Sizing is structural, never content-dependent: cards and bubbles are `height: auto` with `min-height`, so each fits its content exactly instead of flexing (`1fr` made cards and bubbles absorb free space and clip their text under `overflow: hidden`). Overlay effects (cost rain, confetti) live on the toast layer so they never take flow space, and their removal timers are scheduled before their animations start, so a failed animation cannot leak a widget and shrink the layout. Animation frames never re-lay-out: spinner ticks update text with `layout=False` and the elapsed watcher renders once per tick (the old tick rendered twice). Empty states are always labeled (`○ no hits`, `○ no results`, `no changes yet`). --- ## Part 4 — Every tool call, visually specified Family color shown as `▣`. Widgets named are `textual.widgets.*` unless noted. ### 4.1 `read` ▣ cyan — file window with line IDs ``` ┌ ⏳ 📖 read blackcat/agent.py ── scanning… ────────────── ⏱ 12ms ┐ │ 12:4f│ def prompt(self, text): │ │ 13:a1│ """Send a prompt…""" │ │ 14:77│ … │ │ ── 60 lines · window 1–60 · [▼ +312 more] ─────────────────────── │ └──────────────────────────────────────────────────────────────────┘ ``` - Running: `dots` spinner + cyan breathing border; lines stream in 10-line batches with fade-in; a mini `ProgressBar` shows window fill vs 256KB gate. - Body: `TextArea` (read-only, soft-wrap) with `N:hh` gutter in dim + `Syntax` highlighting per extension; verified `N:hh` hashes get a subtle green tick on hover. - Done: `✔ read agent.py — 60 lines (1–60) · ⏱ 12ms`; oversize files show a flashing "paged" ribbon suggesting offset/limit. - Fail (`StaleFileError`/`MustReadFirst`): shake + red strobe; body shows the recovery hint as a glowing amber callout. ### 4.2 `grep` ▣ cyan — regex hits as a strike table ``` ┌ ⏳ 🔎 grep "off.by.one" in blackcat/ ── sweeping… 42 files ── ⏱ ┐ │ ❯ blackcat/converge.py:118 …an offXbyYone scoring tweak… │ │ ❯ blackcat/agent.py:1300 …if self.provider… │ │ ── 3 hits in 2 files · 118 files scanned ───────────────────── │ └────────────────────────────────────────────────────────────────┘ ``` - Running: `earth` spinner; live "N files scanned" ticker counts up; each hit row pops in with `out_bounce`. - Body: `DataTable` (file:line | match with regex span highlighted in amber); click/Enter jumps the Diff tab to that file; footer shows scanned-file count-up. - Done: `✔ grep — 3 hits · 2 files · ⏱ 86ms`. Zero hits: soft amber `○ no hits` (not red — not an error!). ### 4.3 `outline` ▣ cyan — symbol skeleton tree ``` ┌ ⏳ 🗂 outline blackcat/tools.py ── parsing… ─────────── ⏱ 9ms ┐ │ ▼ class FileTools │ ▸ Markdown mode: │ │ ├─ ● read(path, offset, limit) │ # sections as │ │ ├─ ● grep(pattern, path, limit) │ collapsible │ │ └─ ● edit(…) │ tree instead │ └────────────────────────────────────────────────────────────────┘ ``` - Running: `arc` spinner; tree nodes cascade-expand top-down with stagger delay (`delay=i*0.03`, `out_expo`). - Body: `Tree` — classes `▼`, functions `●`, markdown `#`/`##` sections; selecting a node previews its line range in a side peek pane. - Done: `✔ outline tools.py — 9 symbols · ⏱ 9ms`. ### 4.4 `edit` ▣ amber — the star: animated inline diff ``` ┌ ⏳ ✎ edit converge.py ── awaiting approval… [y]es [n]o [a]lways ┐ │ @@ -12,7 +12,7 @@ │ │ context line │ │ − buggy_line = x + 1 (red wash, slides left & fades) │ │ + fixed_line = x + 2 (green wash, slides in from right) │ │ context line │ │ ── 1 match · staleness ✔ fresh · atomic ─────────────────────── │ └──────────────────────────────────────────────────────────────────┘ ``` - Confirming (mutating!): card throbs amber; old/new panes wipe-reveal; `y/n/a` buttons (+ keys) glow. `replace_all` shows a `3/7` match stepper. - Applying: red lines slide left + fade, green lines slide in from right with stagger; gutter signs `−`/`+` stamp with `out_bounce`; hunk header counts tick. - Done: `✔ edit converge.py +7 −3 · ⏱ 31ms`; the Diff tab badge `+1` pops; touched-files rail marks `✎`. - Fail (no match / multiple matches): shake; body lists "did you mean" locations as clickable rows that re-run with the fix. ### 4.5 `multi_edit` ▣ amber — choreographed edit sequence ``` ┌ ⏳ ✎ multi_edit agent.py ── applying 2/5… ▓▓▓▓▓░░░░░ ── ⏱ ┐ │ ✔ #1 lines 44–46 · ✔ #2 lines 130–133 · ⏳ #3 … · ○ #4 · ○ #5 │ │ @@ current hunk diff (same animation as edit)… │ └─────────────────────────────────────────────────────────────────┘ ``` - Running: `ProgressBar` + per-edit checklist lighting up green one by one; current hunk diff animates like `edit`; atomicity banner pulses ("all-or-nothing"). - Done: `✔ multi_edit agent.py — 5/5 applied · ⏱ 64ms`. Any failure rolls the checklist back with a red rewind shimmer (nothing was written!) and the card explains which edit broke. ### 4.6 `write_file` ▣ amber — creation / overwrite ``` ┌ ⏳ ✚ write_file notes/plan.md ── NEW ── writing… ────── ⏱ 8ms ┐ │ + line 1… + line 2… + line 3… (green typewriter cascade) │ │ ── 42 lines · 1.2KB · parent ✔ exists ──────────────────────── │ └────────────────────────────────────────────────────────────────┘ ``` - New file: `✚` badge bursts; content streams as a green typewriter cascade; file appears in the touched rail with a sparkle pop. - Overwrite: requires prior read — shows a mini before/after size bar (`400-line ceiling` gauge fills; `force=true` shows a red "FORCED" ribbon). - Done: `✔ write_file plan.md — 42 lines new · ⏱ 8ms`. ### 4.7 `apply_patch` ▣ violet — V4A patch theatre ``` ┌ ⏳ 🩹 apply_patch ── validating 3 files… ✔✔⏳ ───── ⏱ 21ms ┐ │ ✚ Add File tests/new_t.py │ │ ~ Update File blackcat/cli.py @@ hunks 2 │ │ ── all validated → writing… ────────────────────────────── │ └────────────────────────────────────────────────────────────┘ ``` - Running: two-phase animation — validation checklist first (each file row flips `⏳→✔` with pop), then a violet "writing" sweep across rows; unsupported `Delete File` flashes a red prohibition badge. - Done: `✔ apply_patch — 2 files, 3 hunks · ⏱ 21ms`. Validation failure: the guilty hunk expands with the error underlined in red squiggles, nothing written. ### 4.8 `search` ▣ mint — rsearch results rain ``` ┌ ⏳ 🌐 search "textual animation guide" ── rsearch… ── ⏱ 410ms ┐ │ 1. [Textual Animation — textualize.io] ★ реле 0.91 2026-03-28│ │ Animate opacity, offset… with easing… │ │ 2. [SSC: transitions…] 2024… │ │ ── 8 results · $0.000000 · fallback: none ──────────────────── │ └────────────────────────────────────────────────────────────────┘ ``` - Running: `moon` spinner + "querying rsearch…" shimmer; result rows rain in top-down with stagger; each row: rank, title link (`Link`), domain pill, date, relevance meter micro-bar. - SearXNG fallback (on rsearch failure): card border flips mint→lilac with a "↯ rsearch down — trying SearXNG…" lightning banner; provider pill swaps. - Done: `✔ search — 8 results · $0.000000 · ⏱ 410ms`; `Enter` on a row opens it via `fetch` (card spawns below, linked by a thread line). ### 4.9 `fetch` ▣ sky — page-to-markdown pour ``` ┌ ⏳ 📄 fetch https://…/animation/ ── DeepSeek Fetch… ── ⏱ 900ms ┐ │ ██████████████████████░░░░░░ 18KB poured… │ │ # Animation │ │ This chapter discusses… (Markdown streams in) │ └────────────────────────────────────────────────────────────────┘ ``` - Running: the body is live from the first frame, never an empty bordered box: a `↗ GET ` line, a host line, an indeterminate pour `ProgressBar`, and a ticking `awaiting response… · Ns · provider fetch, Jina Reader fallback armed` status line updated on every spinner tick. The live rows are removed when the result lands. Then the byte-pour bar fills and the Markdown body streams in formatted (headings pop, code fences type in); Jina fallback flips the provider pill to orange "via Jina Reader" with a slide transition. - Done: `✔ fetch — 18KB Markdown · $0.000750 · ⏱ 0.9s`. Paywalled/empty: amber `○ empty page` state with retry button. ### 4.10 `iterative_evidence_convergence` ▣ amber→violet gradient — the showpiece The biggest card: a live mission-control for the whole run. ``` ┌ ⏳ 🧬 converge "coffee improves focus" ── ROUND 2/6 ── conf 0.71 ┐ │ round ▓▓▓▓▓▓░░░░ conf 0.42→0.71 ▲ claims 5 ev 23 contra 1 │ │ Q: "coffee focus RCT" ✓12 "coffee criticism" ✓9 … │ │ top: [0.88] Coffee improves focus [0.31] … │ │ stop-check: conf ✓ · diversity ✓ · stability … · contra ✓ │ │ [tabs: Claims │ Evidence │ Rounds │ Graph] │ └──────────────────────────────────────────────────────────────────┘ ``` - Running: round `ProgressBar`, confidence `Sparkline` climbing live, per-query chips flipping `⏳→✓N`, top-claims leaderboard re-sorting with animated row moves, stop-check checklist ticking, contradiction alerts flashing violet. - Body tabs: Claims (`DataTable` with confidence bars), Evidence (cards per item with reliability stars), Rounds (timeline), Graph (ASCII claim↔evidence map). - Done: confidence number counts up with `out_expo`, big verdict banner unfurls (`✔ CONVERGED 0.87` / `○ max iterations`), cost delta chip pops. Alias `converge_on_claim` renders identically with an `alias` ribbon. ### 4.11 `deep_research` ▣ mint — the research mission strip The fast factual counterpart to convergence (section 4.10): one bounded pass, reported in extreme detail while it runs. ``` ┌ ⏳ 🔬 deep_research "WidgetOS latency" ── 72% · 6 claims · 4 sources ┐ │ ● plan ▸ ● search ▸ ◐ fetch ▸ ○ verify ▸ ○ report │ │ queries 4 · sources 6 · fetched 3 · claims 5 │ │ ✔ WidgetOS latency (6 hits) ✔ WidgetOS latency data (5 hits) … │ │ [1] ▓▓▓▓▓░░░ WidgetOS handbook · docs.example.org │ │ [1] jina · 4,210 chars · 2 claims · provider ✘ → jina ✔ │ │ [1,3] WidgetOS 3.2 cuts latency by 30 percent … (high) │ └──────────────────────────────────────────────────────────────────────┘ ``` - Running: stage stepper (plan, search, fetch, verify, report) with the active stage half-lit, a counters strip, one chip per planned subquery flipping `○ → ✔ N hits`, then one row per ranked source with a `▓░` score bar. Fetching is reported per attempt, live: a row shows `◐ fetching via jina… domain · Ns` with the seconds ticking while an attempt is in flight, flips to `jina ✘ · trying next…` on a fallback hop (card flashes), and lands with the winning method, char count, claim count, and the full fallback chain (`provider ✘ → jina ✔`). Placeholder rows (`planning subqueries…`, `waiting for ranked sources…`) keep the panels populated before the first event, and a UI event handler failure mounts a visible `⚠ ui event … failed` row rather than leaving an empty panel. - Done: `RESEARCHED — NN% confidence` counts up in the verdict banner, claim rows land with `[n]` citation chips colored by confidence (green high, yellow medium, red low), unknowns get warning rows, and the grounded report renders as Markdown below. Confidence at or above 0.85 fires confetti, same as convergence. ### 4.12 Aliases — `write`, `converge_on_claim` Identical cards to `write_file` / `iterative_evidence_convergence`, plus a small `alias →` ribbon in the header so the transcript shows what the model actually called. ### 4.13 Extra surfaces (not tool schemas, still specified) - **`scholar`** ▣ teal: paper cards rain in — title, venue pill, year, citation-count ticker counting up, author line, arXiv/S2 source tabs; `partial` state shows a split card (one side greyed with the error). - **`repo_search`** ▣ lilac: `DataTable` of path/line/snippet/score with animated score bars; "index fresh: +3 ~1" toast; index path + file count in header. - **chat/prompt streaming**: assistant bubble with `Markdown` streaming (typewriter + fade per block), model pill, live token ticker, `▸ streaming` → `✔ done · 1.2k tok · $0.0018`; images via `textual-image` thumbnails above the bubble. - **`/costs`**: `Digits` total counting up, `DataTable` by category × provider, cost `Sparkline` per turn, per-model rows. - **`models`**: provider-grouped `OptionList` with context/feature badges; selecting one switches the header pill with a flash. - **`note`/`compact`**: notes slide into a "memory" tray; compaction shows a vacuum animation (old tool bodies collapse with stagger, summary types in, context gauge drains green). - **Errors everywhere**: `unknown_tool`/`bad_args`/`tool_exception`/`security`/`MustReadFirst`/`StaleFile` all share the shake+strobe treatment, an error-code chip, and a one-click "copy error" + "re-read file" quick-fix row. ### 4.14 `bash` ▣ rose - live terminal stream ``` ┌ ⏳ 💻 bash pytest -q ── running… ── ⏱ 12ms ┐ │ $ pytest -q │ │ cwd . · timeout 120s │ │ ....F.. │ └─────────────────────────────────────────────┘ ``` - Running: the command line and cwd pin at the top; process output appends into one live row as it arrives (single render per chunk, no re-layout), so long test runs and scans visibly stream instead of spinning silently. - Done: `✔ bash pytest -q - exit 0 · 1.2s`; stdout/stderr land as separate capped sections with byte counts and a `truncated` flag when the cap hit. Non-zero exits keep their output (exit code is data, not a card error); timeouts show a warning row plus partial output; `bad_args`/`security`/`io` use the shared failure body. - Approval: `bash` is a mutating tool, so the card throbs amber for `y/n/a` like any edit; `--yolo` and auto-approve skip it, and read-only sessions refuse with the `security` code. --- ## Part 5 — Maximum flash: global showpieces 1. **Boot splash**: ASCII black cat with blinking amber eyes, gradient `BLACKCAT` title wipe, shimmer "warming up the alley…" — slides away on ready. 2. **Reactive mascot**: header cat eyes track state (slow-blink idle, fast-blink streaming, spinning during converge, red flash on error, sunglasses on `/costs` under budget). 3. **Spinner wardrobe** (never reuse twice in a row): `dots`, `arc`, `earth`, `moon`, `shark`, `pong`, `aesthetic`, `material` — assigned per tool family (§4). 4. **Cost rain**: every billable call fires a `+$0.0018` chip that floats up from the footer and dissolves into the `Digits` total. 5. **Confetti mode**: on `✔ CONVERGED ≥ 0.85` or 10 green tools in a row — falling `✦` particles across the transcript (timed `Static` rain, auto-clears). 6. **Command palette** (`Ctrl+P`): every action fuzzy-searchable — tools, `/costs`, `/diff`, `/models`, theme switch, "explain this error", "copy transcript". 7. **Slash menu**: typing `/` opens an inline `OptionList` (`/costs /diff /models /help /quit /theme /report`). 8. **Session diff tab**: accumulated unified diff of the whole run, hunks folding in live; `d` toggles gutter-sign mode. 9. **Toast chorus**: `App.notify` on every tool completion/fallback/compaction, severity-toned, click-to-jump to the card. 10. **Theme switcher**: Alley Cat (dark) / Milk Bowl (light) / Matrix Alley (green-on-black) via palette; instant TCSS variable swap with a screen flash. 11. **Sound-ish feedback**: terminal bell patterns (short ok-blip, double error-buzz) behind a mute toggle. 12. **Idle attract mode**: after 60s idle, the cat naps (`Z z z` float up) until next keypress. ### Keybindings `Enter` send · `Shift+Tab` newline · `↑/↓` history · `Ctrl+O` expand/collapse card · `Ctrl+P` palette · `j/k` move between cards · `y/n/a` approve · `d` diff tab · `c` costs · `1..4` right-panel tabs · `t` theme · `/` slash menu · `q` quit · `Ctrl+C` cancel running card (triple press aborts the turn) · mouse fully supported (click, scroll, hover, resize panes). ## Part 6 — Build roadmap - **Phase 0 — spike**: `blackcat/tui/app.py` with shell layout + theme + echo-provider transcript; prove 60fps card animations. - **Phase 1 — cards**: `ToolCard` base + all 10 tool renderers streaming from `BlackCatBot.run_tool` hooks (wrap dispatch with UI events; no core logic changes). - **Phase 2 — chrome**: rails, tabs (Diff/Costs/Report/Models), palette, slash menu, approvals (`tool_confirm` → approval cards), toasts. - **Phase 3 — showpieces**: splash, mascot, cost rain, confetti, vision thumbnails (`textual-image`, optional dep), themes, attract mode. - **Phase 4 — hardening**: `Pilot` headless tests per card state (pending/running/ok/failed/confirming), 80×24 responsive pass, ASCII fallback glyph mode, `textual-web` deploy check. - Deps: `textual>=6`, `textual-image` (optional, vision), `pygments` (comes with Rich). Core stays zero-dependency; TUI is an extra (`pip install blackcat[tui]`). ``` blackcat/tui/ app.py # BlackCatApp, screens, palette, keybindings theme.py # Alley Cat / Milk Bowl / Matrix Alley Theme registration cards.py # ToolCard base + per-tool card widgets (§4.1–4.14) chrome.py # rails, tabs, footer telemetry, splash screen bridge.py # BlackCatBot → UI event bridge (workers, no core edits) blackcat.tcss # all styling, transitions, :hover states tests/test_tui.py # Pilot tests for every card state ``` ## Sources (research) - Coding-assistant UI patterns survey (Cursor/Copilot/Aider/Claude Code/Continue/Replit/Lovable/Cody) — tool cards, streaming output, tool timeline - OpenCode TUI analyses — inline diffs, color-coded trees, visible tool logs; ACP `tool_call` kinds/statuses + `diff` content variant - Gemini CLI UI component docs (DeepWiki) — `ToolMessage`/`ToolGroupMessage`, `ToolStatusIndicator` lifecycle glyphs, `ToolConfirmationMessage`, `DiffRenderer`, `GeminiRespondingSpinner`, `AutoAcceptIndicator` - Codex/Gemini provider comparison — expandable tool details, `/diff`, `/approvals`, `/statusline`, progress spinners - Textual official docs — widget gallery, animation guide (`animate`, easings, `on_complete`, `delay`), themes guide, `LoadingIndicator`, workers, command palette - `textual-image` (PyPI) + fast-agent TUI — Kitty TGP/sixel/halfcell image rendering in Textual apps - Misc: Claude Code vs OpenCode TUI comparison; `shoulder` multi-agent TUI (inline red/green diffs, gutter signs); closed-code phase spec (modal approval overlay, full-screen diff viewer)