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. 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 (usage), AGENTS.md
(agent rules), 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'sAutoAcceptIndicator: 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 step3/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 identicalstyles.animate(...)- animate opacity, offset, height, colors, scrollbar position.- Easing: full easings.net set; default
in_out_cubic; preview withtextual easing(needstextual-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;) +:hoverstates for free micro-motion. reactive()attributes +watch_*hooks: state changes auto-repaint; drive spinners, counters, gauges from reactives.@work/run_worker+Worker.StateChangedmessages: network/LLM/subprocess stay off the event loop; stream partial results viacall_from_thread/ message pump.App.notify()toasts, modalScreens (push_screen), built-in Command Palette (CommandPalette, providers returningHits),App.register_theme()+Themevariables ($primary,$success,$warning,$error, surfaces, borders, scrollbar…) with light/dark variants,textual keys/textual diagnosedevtools.
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 (
TabbedContentorContentSwitcher): Sessions list, Touched-files tree (dirty✎/✚/✘badges), context gauge (ProgressBar+ %), live cost (Digitsmini +Sparkline), elapsed clock. - Center:
RichLogtranscript - user bubbles, assistant Markdown stream, tool cards, approval cards, dividerRules per turn. - Right panel (
TabbedContent): Diff (accumulated session diff,TextArearead-only), Costs (DataTable + sparkline), Report (PrettyJSON ofsave_report), Models, Help. - Bottom: multiline
TextAreaprompt box with focus glow + one-lineFooterstatus (step3/16, spinner state, key hints). Prompt-box parity with the CLI:Up/Downhistory,Shift+Tabnewline-without-send, multiline paste as one prompt (seerun_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)):
┌ ⏳/✔/✘ <icon> <tool> <target…> ── <live status / result summary> ── <⏱ 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:
dotsspinner + cyan breathing border; lines stream in 10-line batches with fade-in; a miniProgressBarshows window fill vs 256KB gate. - Body:
TextArea(read-only, soft-wrap) withN:hhgutter in dim +Syntaxhighlighting per extension; verifiedN:hhhashes 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:
earthspinner; live "N files scanned" ticker counts up; each hit row pops in without_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:
arcspinner; 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/abuttons (+ keys) glow.replace_allshows a3/7match stepper. - Applying: red lines slide left + fade, green lines slide in from right with stagger; gutter signs
−/+stamp without_bounce; hunk header counts tick. - Done:
✔ edit converge.py +7 −3 · ⏱ 31ms; the Diff tab badge+1pops; 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 likeedit; 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 ceilinggauge fills;force=trueshows 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; unsupportedDelete Fileflashes 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:
moonspinner + "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;Enteron a row opens it viafetch(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 <url>line, a host line, an indeterminate pourProgressBar, and a tickingawaiting response… · Ns · provider fetch, Jina Reader fallback armedstatus 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 pagestate 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, confidenceSparklineclimbing 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 (
DataTablewith 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. Aliasconverge_on_claimrenders identically with analiasribbon.
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 · Nswith the seconds ticking while an
attempt is in flight, flips tojina ✘ <error> · 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 … failedrow rather than leaving an empty panel. - Done:
RESEARCHED - NN% confidencecounts 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;partialstate shows a split card (one side greyed with the error).repo_search▣ lilac:DataTableof 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
Markdownstreaming (typewriter + fade per block), model pill, live token ticker,▸ streaming→✔ done · 1.2k tok · $0.0018; images viatextual-imagethumbnails above the bubble. /costs:Digitstotal counting up,DataTableby category × provider, costSparklineper turn, per-model rows.models: provider-groupedOptionListwith 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/StaleFileall 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 atruncatedflag 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/iouse the shared failure body. - Approval:
bashis a mutating tool, so the card throbs amber fory/n/alike any edit;--yoloand auto-approve skip it, and read-only sessions refuse with thesecuritycode.
Part 5 - Maximum flash: global showpieces
- Boot splash: ASCII black cat with blinking amber eyes, gradient
BLACKCATtitle wipe, shimmer "warming up the alley…" - slides away on ready. - Reactive mascot: header cat eyes track state (slow-blink idle, fast-blink streaming, spinning during converge, red flash on error, sunglasses on
/costsunder budget). - Spinner wardrobe (never reuse twice in a row):
dots,arc,earth,moon,shark,pong,aesthetic,material- assigned per tool family (§4). - Cost rain: every billable call fires a
+$0.0018chip that floats up from the footer and dissolves into theDigitstotal. - Confetti mode: on
✔ CONVERGED ≥ 0.85or 10 green tools in a row - falling✦particles across the transcript (timedStaticrain, auto-clears). - Command palette (
Ctrl+P): every action fuzzy-searchable - tools,/costs,/diff,/models, theme switch, "explain this error", "copy transcript". - Slash menu: typing
/opens an inlineOptionList(/costs /diff /models /help /quit /theme /report). - Session diff tab: accumulated unified diff of the whole run, hunks folding in live;
dtoggles gutter-sign mode. - Toast chorus:
App.notifyon every tool completion/fallback/compaction, severity-toned, click-to-jump to the card. - Theme switcher: Alley Cat (dark) / Milk Bowl (light) / Matrix Alley (green-on-black) via palette; instant TCSS variable swap with a screen flash.
- Sound-ish feedback: terminal bell patterns (short ok-blip, double error-buzz) behind a mute toggle.
- Idle attract mode: after 60s idle, the cat naps (
Z z zfloat 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.pywith shell layout + theme + echo-provider transcript; prove 60fps card animations. - Phase 1 - cards:
ToolCardbase + all 10 tool renderers streaming fromBlackCatBot.run_toolhooks (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:
Pilotheadless tests per card state (pending/running/ok/failed/confirming), 80×24 responsive pass, ASCII fallback glyph mode,textual-webdeploy 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_callkinds/statuses +diffcontent variant - Gemini CLI UI component docs (DeepWiki) -
ToolMessage/ToolGroupMessage,ToolStatusIndicatorlifecycle 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;
shouldermulti-agent TUI (inline red/green diffs, gutter signs); closed-code phase spec (modal approval overlay, full-screen diff viewer)