SumoCode is what happens when a frontend engineer
decides the terminal needs design.

SumoCode is a Pi extension that turns a generic terminal AI agent into a personal one — with persistent memory, a custom-built retained renderer, three themes, and five preattentive status colors.

The value proposition holds three pieces. First: identity persists. A persona file is appended to every system prompt; the agent introduces itself the same way on every session, every machine. Second: state is visible. A single colored dot in the footer tells you in <250ms whether the agent is idle, thinking, running a tool, awaiting approval, or writing to memory. Third: the renderer is real. SumoCode owns the alternate screen, mouse routing, in-app scroll, modal layers, and a Yoga-based flexbox layout — none of which Pi's default renderer offers.

Before any code, here is the cheat sheet. Once these mappings click, the rest of the architecture follows naturally:

Here's a tiny sample of what an ANSI-encoded chat row actually looks like, expanded so you can see the structure:

// What you see on screen:                                       
// ~/sumocode (main) · ↑12k ↓8k · $0.42 · ● READY · sonnet-4.5

\x1b[H                                  // move cursor home
\x1b[38;2;245;230;200m                // fg = #F5E6C8 (parchment)
\x1b[48;2;26;21;17m                  // bg = #1A1511 (cathedral bg)
~/sumocode \x1b[2m(main)\x1b[22m · ↑12k ↓8k · $0.42 ·
\x1b[38;2;127;176;105m●\x1b[0m READY · sonnet-4.5
\x1b[K                                 // clear to end of line

Each layer only knows about the layer immediately below. The Cathedral layer doesn't know how Yoga works; it just registers components with ctx.ui.setFooter(...). SumoTUI doesn't know how Pi's tools work; it just renders ChatBlock objects from a transcript view-model. This separation is what makes the codebase scalable despite spanning 96 modules.

SumoTUI is a retained renderer. That word matters: the alternative ("immediate mode") is what Pi originally used — every render rebuilds the entire frame from scratch, every time. Retained means we keep a tree of nodes around between frames and only re-layout / re-composite the parts that change.

Here's what happens when, say, the working indicator ticks one frame forward:

The CellBuffer · your «DOM»

Every visible character on screen is one Cell. A cell holds:

interface Cell {
    char: string;           // "A", "日" (2-wide), or "" (continuation)
    fg:   string | null;    // "#F5E6C8"
    bg:   string | null;    // "#1A1511"
    attrs: {
      bold: boolean;
      italic: boolean;
      underline: boolean;
      dim: boolean;
      inverse: boolean;
    }
}

// CellBuffer is rows × cols of these
class CellBuffer {
    private chars: Uint16Array;  // hot path uses typed arrays
    private fg: Map<number, string>;     // sparse: most cells share fg/bg
    private bg: Map<number, string>;
    private attrs: Map<number, number>;   // packed bitfield
}

The optimization that matters: most cells in a frame are blank or share the same style as their neighbors. Storing fg/bg/attrs in sparse Maps instead of dense arrays cuts memory by 90% in typical frames. The diff algorithm then walks rows in linear time, finding the leftmost and rightmost differing column per row, and emits the smallest possible ANSI patch.

Why Yoga, specifically

Yoga is Facebook's flexbox engine — the same one that powers React Native, Litho, and ComponentKit. SumoCode uses yoga-wasm-web: 87KB of WASM, no native build step, identical layout semantics to web flex. The retained tree isn't custom; it's CSS flex with terminal-cell units.

This means the splash screen's "vertical center" isn't padding math. It's:

Root(flexDirection: column, flexGrow: 1)
  ├─ TopSpacer(flexGrow: 1)     // fills available space
  ├─ Splash(flexShrink: 0)      // fixed: cat + wordmark + quote
  └─ BottomSpacer(flexGrow: 1)  // fills available space

// Yoga splits free rows 50/50 between the spacers.
// Resize the terminal? Layout recomputes for free.

Six phases, ~700-1100ms cold start. Each phase has its own actor:

The jiti transpile step (~300ms in the cold path) is the single largest cost. It exists because sumo-interactive-mode.js bridges Pi's CommonJS-loaded patch into our TypeScript source on the fly. Pre-compiling that entry point into a real JS bundle would cut cold start by half — already filed as a P0 in the perf audit.

Phases in human terms:

• Shell handshake — bash launcher inspects Pi's dist/main.js for the patch marker, sets SUMO_TUI_MODULE to a file:// URL pointing at our bridge, then execs Pi.
• Pi bootstrap — provider config, model registry, MCP server connections, session manager. Pi-owned.
• Bridge load — Pi's patched main.js reaches the constructor site, sees SUMO_TUI=1, dynamically imports our bridge, and instantiates SumoInteractiveMode instead of InteractiveMode.
• Retained runtime start — Yoga WASM initialization, splash tree creation, ChatPager allocation, frame scheduler bootstrap, terminal session entry (altscreen + mouse + kitty + paste mode).
• Extension install — Pi loads src/extension.ts, which calls 14 install* functions. Each registers handlers but defers all DOM-equivalent work to session_start.
• First paint — Pi emits session_start; the cascade of handlers populates widgets; Yoga lays out; the compositor produces the first CellBuffer; diff produces patches; ANSI hits stdout; user sees the cat.

Pi exposes its tool system through three different surfaces, and SumoCode has to integrate with each one differently. This is the table that took me longest to internalize:

The transcript view-model

Every chat message — user, assistant, tool, skill, delegation — flows through one shared view-model before any rendering happens:

type ChatBlock =
  | { type: "markdown"; text: string }
  | { type: "code"; lang: string; source: string }
  | { type: "tool"; tool: ToolCallViewModel }
  | { type: "skill"; name: string; expanded: boolean }
  | { type: "question"; question: QuestionViewModel }
  | { type: "delegation"; delegation: DelegationViewModel };

type ChatMessageViewModel = {
    id: string;
    role: "user" | "sumo" | "system";
    blocks: ChatBlock[];
};

This abstraction is the lever that makes everything downstream possible. The visual harness can build deterministic transcripts without running an LLM. The chat renderer can switch on block type without parsing strings. New block types (like delegation pills for sub-process scrolls) ship as additions to the union — no renderer changes needed elsewhere.

The 14 install hooks

The extension entry point is intentionally boring — it's just an ordered list of installations. Order matters: render diagnostics installs first so it can wrap every later setFooter/setWidget call; session cache installs second so its invalidation runs alongside producer updates.

export default function sumocode(pi: ExtensionAPI): void {
    installRenderDiagnostics(pi);    // 01: wrap UI calls
    installSessionCache(pi);          // 02: cache token tally + git branch
    installAltscreen(pi);             // 03: lifecycle + signal cleanup
    installTopChrome(pi);             // 04: top header bar
    installSplash(pi);                // 05: cathedral splash widget
    installFooter(pi);                // 06: status footer
    installCathedralEditor(pi);       // 07: input frame chrome
    installInputHints(pi);            // 08: keybind hint row
    installApprovalGate(pi);          // 09: dangerous bash guard
    taskTool({...})(pi);              // 10: native parallel task
    installQuestionTool(pi);          // 11: divine query override
    installAnswerTool(pi);            // 12: /answer wizard
    installWorkingIndicator(pi);      // 13: theme-aware spinner
    installSumoInteractions(pi);      // 14: slash commands + shortcuts
}

Pi is a public, maintained npm package. SumoCode is a Pi extension — but extensions only get to register components, not replace Pi's interactive constructor. To own the alternate screen lifecycle, mouse routing, scroll, and modal layers, we need to be the InteractiveMode that Pi instantiates.

The fix is a 12-line patch on Pi's dist/main.js that swaps the constructor when an env var is set:

-const interactiveMode = new InteractiveMode(runtime, options);
+const useSumoTui = isTruthy(process.env.SUMO_TUI) || parsed.unknownFlags.has("sumo-tui");
+const interactiveMode = useSumoTui
    ? await loadSumoInteractiveMode(runtime, options)
    : new InteractiveMode(runtime, options);

async function loadSumoInteractiveMode(...args) {
    const spec = process.env.SUMO_TUI_MODULE ?? "@dhruvkelawala/sumocode/sumo-interactive-mode";
    const { SumoInteractiveMode } = await import(spec);
    return new SumoInteractiveMode(...args);
}

The contract is explicit:

• Default-off. Without SUMO_TUI=1, Pi behaves exactly like vanilla Pi. Other Pi users are unaffected.
• Runtime-gated. Activation is one env var. Disable per-launch with --no-sumo-tui.
• Wrapper-checked. The sumocode shell launcher inspects the patch marker before activating. Patch missing? Falls back to legacy Pi UI with a warning.
• Pinned to Pi 0.70.x. Pi version bumps follow a documented smoke matrix (docs/research/pi-fork-upgrade.md).
• Revisitable. When Pi exposes a public interactive-mode injection API, we delete the patch.

This isn't ideology — it's pragmatism. opentui-island's sidecar architecture would have cost ~500ms cold start and ~400MB RSS for our four chrome regions. Forking Pi entirely would have meant re-implementing the LLM/agent/tool/MCP surface. The 12-line patch is the smallest mutation that gets us where we need to be.

Preattentive processing is the visual-perception term for "things you notice before you decide to look." Cone-density-aware research shows you can disambiguate ~5 hues simultaneously in your peripheral vision. SumoCode picks five and assigns one agent state to each:

The dot lives in the footer's right zone. The state name (uppercase, Cathedral verb) appears next to it. Both are theme-driven — switching to Obsidian Temple swaps colors but keeps the semantics identical.

The Cathedral palette

The default theme is named for its visual reference: a 19th-century scriptorium. Warm walnut surfaces, parchment foreground, burnt-orange accent. Every color is a typed token in src/themes/cathedral.ts:

export const CATHEDRAL_THEME: Theme = {
    name: "cathedral",
    tokens: { colors: {
        background: "#1A1511",      // walnut deep
        surface: "#241D17",         // walnut mid (sidebar bg)
        foreground: "#F5E6C8",      // parchment
        foregroundDim: "#8B7A63",   // muted brown for dim text
        accent: "#D97706",          // burnt orange — single accent
        states: {
            idle: "#7FB069", thinking: "#E8B339",
            tool: "#5B9BD5", approval: "#C1443E",
            learning: "#8E7AB5"
        },
    } },
    workingIndicator: { frames: ["◌", "✦", "❖", "✺", "❋", "❉"], intervalMs: 150 },
    chrome: { ...DEFAULT_CHROME },                           // box-drawing glyphs
};

The chrome object holds the structural vocabulary — frame corners, dividers, bullets, section glyphs. Themes can override these to feel completely different even with similar colors. Obsidian Temple uses the same five state hues but at higher saturation against a near-black surface and adds neon glow effects via terminal-supported underlines.

Switching themes is Ctrl+Shift+T. The runtime emits a theme_changed event; every retained component clears its frame cache; the next render produces fresh ANSI for the new palette. Zero flicker, zero re-layout.

This is my favorite piece. Visual regressions in TUIs are notoriously hard to catch — a single off-by-one column or stale ANSI reset can make a perfectly correct algorithm produce a broken-looking screen. SumoCode runs three convergent verification lanes:

All three converge into a shared verification pipeline:

The non-obvious decision: the styled-cell diff is the primary CI gate, not the PNG diff. Pixel-level PNG comparison is flaky (font rendering, sub-pixel anti-aliasing, OS color profiles). Comparing per-cell {char, fg, bg, bold, dim} against a parsed Bible HTML reference is deterministic across machines.

The Bible HTML files at docs/ui/bible/*.html are the canonical visual reference — hand-built mockups exported from Stitch, then promoted to source-of-truth. PNG renders of those Bible files exist as review evidence, not gates.

Runtime

Test & harness

Build & release

Module shape

• src/ — extension entry, cathedral chrome modules, themes, commands, slash command registry. ~7k lines.
• src/sumo-tui/ — retained renderer foundation. Layout, render, input, runtime, widgets, transcript, pi-compat. ~11k lines.
• src/sumo-tui/cathedral/ — Cathedral-specific retained nodes (splash tree, tool pills, message frames). Sits on top of sumo-tui primitives.
• src/sumo-tui/pi-compat/ — the only place sumo-tui touches Pi internals. SumoInteractiveMode, owned-shell renderer, Pi noise filter, foreign extension warning.
• test/integration/ — node-pty PTY tests for altscreen cleanup, mouse routing, signal handling, splash centering.
• docs/ — ADRs, research artifacts, visual contracts, Bible HTML/PNG references.
• patches/ — the 12-line Pi constructor patch.
• bin/sumocode.sh — the launcher with doctor/diag/dry-run/--no-sumo-tui modes.

What's defensible to claim

• "Built a retained terminal renderer in TypeScript" — true, ~11k lines under src/sumo-tui/. Yoga + CellBuffer + frame diff + altscreen + mouse SGR.
• "~50-90% byte savings per streaming frame" — true, from the per-row column-range diff (cite OpenTUI as inspiration).
• "Five preattentive state colors, <250ms recognition" — true, this is the explicit UX target.
• "Three themes, one keypress to cycle" — true, Ctrl+Shift+T.
• "Twelve-line patch on Pi to swap the interactive constructor" — true, default-off, runtime-gated, wrapper-checked.
• "Verified with three convergent visual lanes" — true, component + fixture + runtime PTY all converge through xterm replay.

What I would not lead with

• The cold-start time — currently ~700-1100ms, dominated by jiti transpile. Fix this before launch (see perf audit) or avoid the topic.
• "Better than <tool X>" — SumoCode is a personal extension built on Pi. Frame it as "what's possible when you own the experience layer", not as a competitor.
• Cross-platform claims — macOS only for v1. Linux/Windows is on the roadmap, not shipped.
• Memory features — Remnic memory daemon is in PRD, not shipped in v0.1.0. Don't promise what's not built.

A draft tweet thread

One-line elevator

SumoCode is shadcn/ui for terminal AI agents — built on @mariozechner/pi-mono, with a retained renderer that owns the alternate screen and treats every state as a typed token.