Building a Terminal UI Broke My Brain

#cli #tui

I’ve spent most of my career building things for the browser.

If something looks wrong, you open DevTools.
If spacing is off, you inspect the DOM.
If the layout is cursed, you tweak CSS until it stops yelling at you.

So naturally, I thought building a Terminal UI (TUI) would be… similar.

It was not!

This post is part of me building in public while working on a project called TurboStream — a developer tool that lets you connect high-velocity WebSocket streams (blockchains, BGP, finance feeds, etc.) to LLMs without draining tokens or crashing your system.

Think:

WebSocket → Cache → Triggers → LLM → Short human-readable alerts.

The backend was the easy part.
The Terminal UI nearly ended me.

Coming From the Browser World

In the web world:

Figma → HTML/CSS is mostly mechanical
Layout is visual
Debugging is interactive

In Bubble Tea land:

Layout is math
Padding is vibes
“Why is this box 2 columns wider?” is a philosophical question

There’s no DOM inspector.
There’s no “hover to see bounding box.”
You change one lipgloss.Style() and suddenly everything shifts.

The Hardest Screen: AI Analysis

The screen that caused the most pain was the AI Analysis panel.

Conceptually, it’s simple:

show LLM context size
show token usage
show generation timing
stream output text

In reality:

content height changes constantly
widths need to stay aligned with sibling panels
scrolling text + borders + padding fight each other

I kept ending up with:

truncated text
panels overflowing by 1 character
borders misaligned depending on terminal width

It looked fine at one size, then completely broke when resized.

If you’ve used Bubble Tea, you know the feeling:
“This should work… why doesn’t it?”

What I Learned (So Far)

A few lessons that finally started to click:

1. Stop thinking in pixels

Terminal layout is about constraints, not visuals.
Everything is rows × columns. Nothing is free.

2. Measure everything explicitly

If you don’t calculate width/height yourself, Bubble Tea will happily surprise you.

3. Borders lie

Borders and padding count.
That “one extra column” is always your fault.

4. Debugging TUIs requires instrumentation

I started adding:

temporary background colors
width/height labels inside boxes
fake content to stress layouts

It felt ugly — but it worked.

What I’m Doing Next

To make this sane long-term, my next steps are:

Create a layout debug mode: Toggleable overlays that show component boundaries and sizes.
Write small layout test harnesses: Instead of debugging inside the full app, isolate one view at a time.
Standardize layout contracts: Every panel declares what it needs instead of “figuring it out.”
Accept that TUI UX ≠ Web UX: Different medium, different rules