Skip to content
Repos

blackcat

Markdown 35.7 KB461 lines Opens in site

Directory Raw Download

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'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 Screens (push_screen), built-in Command Palette (CommandPalette, providers returning Hits), 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 Rules 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)):

┌ ⏳/✔/✘  <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: 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 <url> 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 ✘ <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 … 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)
457.8ms