@@ -53,6 +53,7 @@ This replaces: `yoctocolors`, `yoctomarkdown`, `yoctoselect`, and all our custom
5353
5454 - **Runtime**: Bun — for runtime, bundling, testing, and `bun:sqlite`.
5555 - **Schema validation**: TypeBox (re-exported from pi-ai) for tool schemas.
56+- **Diffing**: `diff` (jsdiff) — `structuredPatch` for line-level unified diffs in edit tool output.
5657
5758 ## Tools
5859
@@ -161,6 +162,8 @@ interface PluginResult {
161162 tools?: Tool[];
162163 /** Additional context to append to the system prompt. */
163164 systemPromptSuffix?: string;
165+ /** Partial theme override — merged on top of the default theme. */
166+ theme?: Partial<Theme>;
164167 }
165168
166169 interface AgentContext {
@@ -382,27 +385,31 @@ Key decisions informed by the Codex prompting guide and Claude prompting best pr
382385 Three zones, top to bottom:
383386
384387 ```
385-┌──────────────────────────────────────────────┐
386-│ │
387-│ Conversation log │
388-│ (scrollable, flex: 1) │
389-│ │
390-│ ▶ User: fix the tests │
391-│ │
392-│ ▷ Agent: I'll check the test suite... │
393-│ ┌─────────────────────────────┐ │
394-│ │ $ bun test │ │
395-│ │ 3 passed, 1 failed │ │
396-│ └─────────────────────────────┘ │
397-│ Fixed the assertion in... │
398-│ │
399-├──────────────────────────────────────────────┤
400-│ > fix the remaining lint warnings │
401-│ in the utils file too │
402-├──────────────────────────────────────────────┤
403-│ ~/src/mini-coder main +3 ~1 ▲ 2 │
404-│ anthropic/sonnet-4 · med in:1.2k out:0.8k 42% $0.03 │
405-└──────────────────────────────────────────────┘
388+│ │
389+│ ┌─────────────────────────────────────────────┐ │
390+│ │ fix the tests │ │ user: bg color
391+│ └─────────────────────────────────────────────┘ │
392+│ │
393+│ I'll check the test suite first. │ agent: default bg
394+│ │
395+│ │ $ bun test │ tool: left border
396+│ │ 3 passed, 1 failed │ dimmed text
397+│ │ ... truncated 45 lines ... │
398+│ │ FAIL src/agent.test.ts > handles error │
399+│ │ exit 1 │
400+│ │ │
401+│ │ ~ src/agent.ts │ edit: path + diff
402+│ │ - expect(result).toBe("stop"); │ red removed
403+│ │ + expect(result).toBe("error"); │ green added
404+│ │ │
405+│ Fixed the assertion. Tests pass now. │
406+│ │
407+────══════─────────────────────────────────────────── animated divider
408+ fix the remaining lint warnings │ input: no prefix
409+ in the utils file too_ │
410+───────────────────────────────────────────────────── static divider
411+ ~/src/mini-coder main +3 ~1 A 2 │ status line 1
412+ anthropic/sonnet-4 · med in:1.2k out:0.8k 42% $0.03│ status line 2
406413 ```
407414
408415 cel-tui structure:
@@ -411,21 +418,47 @@ cel-tui structure:
411418 VStack({ height: "100%" }, [
412419 // Conversation log — takes all available space
413420 VStack({ flex: 1, overflow: "scroll", scrollbar: true }),
421+ // Top divider — animated scanning pulse when agent is working
414422 Divider(),
415- // Input area — intrinsic height, grows up to maxHeight
416- HStack({ padding: { x: 1 } }, [
417- Text(">"),
418- TextInput({ flex: 1, maxHeight: 10 }),
419- ]),
423+ // Input area — intrinsic height, no prompt prefix
424+ VStack({ padding: { x: 1 } }, [TextInput({ flex: 1, maxHeight: 10 })]),
425+ // Bottom divider — always static
420426 Divider(),
421427 // Status bar — fixed 2 lines
422- VStack({ height: 2 }, [
428+ VStack({ height: 2, padding: { x: 1 } }, [
423429 HStack([Text(cwd), Spacer(), Text(gitStatus)]),
424430 HStack([Text(modelInfo), Spacer(), Text(usage)]),
425431 ]),
426432 ]);
427433 ```
428434
435+### Theme
436+
437+All UI colors are defined in a single `Theme` object. The UI never hardcodes colors — it reads from the active theme. Plugins can return a `Partial<Theme>` in their `PluginResult` to override any color. Multiple plugin overrides are merged left-to-right (last wins).
438+
439+```ts
440+interface Theme {
441+ /** User message background. */
442+ userMsgBg: string;
443+ /** Tool output left border and text. */
444+ toolBorder: string;
445+ toolText: string;
446+ /** Diff colors in edit tool output. */
447+ diffAdded: string;
448+ diffRemoved: string;
449+ /** Divider line color (idle state). */
450+ divider: string;
451+ /** Divider scanning pulse highlight color (active state). */
452+ dividerPulse: string;
453+ /** Status bar foreground. */
454+ statusText: string;
455+ /** Error text. */
456+ error: string;
457+}
458+```
459+
460+The default theme uses terminal palette colors (e.g., `color08` for dimmed, `color02` for green, `color01` for red) so it adapts to the user's terminal color scheme. Theme values are cel-tui color strings.
461+
429462 ### Status bar
430463
431464 Two lines, four corners:
@@ -453,18 +486,18 @@ Scrollable area that shows the full conversation history. Stick-to-bottom by def
453486
454487 Message types and their rendering:
455488
456-- **User messages**: prefixed with a role indicator and displayed as plain text.
457-- **Assistant messages**: streamed markdown rendered via cel-tui's `Markdown` component. Thinking/reasoning content is collapsible (hidden by default, toggled with `/reasoning`).
458-- **Tool calls — shell**: show the command, then stdout/stderr. Output is truncated in the UI (head + tail) with a visual marker. Full output viewable with `/verbose`.
459-- **Tool calls — edit**: show the file path and a brief summary (e.g., "edited 3 lines in `src/agent.ts`"). No full diff in the log.
460-- **Tool calls — plugin tools**: prefixed with plugin/tool name.
489+- **User messages**: displayed as plain text with a subtle background color to distinguish them from agent responses. No prefix or role indicator.
490+- **Assistant messages**: streamed markdown rendered via cel-tui's `Markdown` component on the default background. Thinking/reasoning content is collapsible (hidden by default, toggled with `/reasoning`).
491+- **Tool calls — shell**: rendered with a left border (`│`) and dimmed foreground. Shows the command (`$ command`), head + tail truncated output with a visual marker, and exit code. Full output viewable with `/verbose`.
492+- **Tool calls — edit**: rendered with a left border (`│`) and dimmed foreground. Shows the file path and a unified diff of the change (added lines in green, removed in red). Uses the `diff` package (`structuredPatch`) for line-level diffing.
493+- **Tool calls — plugin tools**: rendered with a left border, prefixed with plugin/tool name.
461494 - **Errors**: one-line summary, styled distinctly.
462495
463-While the agent is working, an inline spinner with an activity label ("thinking", "running shell", "editing") appears at the end of the log.
496+While the agent is working, the top divider (above the input area) animates with a scanning pulse — a bright segment sweeping across the dimmed divider line. The animation starts when a turn begins and stops when the turn ends (done, error, or aborted). No per-activity state tracking.
464497
465498 ### Input area
466499
467-Multi-line text input. Intrinsic height (1 line when empty, grows with content) up to `maxHeight: 10`, then scrolls internally. cel-tui's `TextInput` with `submitKey: "enter"` (Enter submits, Shift+Enter adds newlines).
500+Multi-line text input with no prompt prefix — the blinking cursor is the affordance. Intrinsic height (1 line when empty, grows with content) up to `maxHeight: 10`, then scrolls internally. cel-tui's `TextInput` with `submitKey: "enter"` (Enter submits, Shift+Enter adds newlines).
468501
469502 Supports:
470503