stock-tui: building a stock market heatmap for the terminal

A favorite old interface, moved sideways

StockTouch arranged the market as a wall of red and green tiles. stock-tui keeps that visual model but changes the medium: a 3×3 overview of nine economic sectors, up to 100 companies inside each sector, then a ticker screen with price, volume, statistics, and news.

“Represent stocks as color-coded rectangles, moving from bright red through dark red and neutral gray to dark green and bright green.”

From the first prompt to Codex

The opening prompt was broad, but it was not vague. It named the interaction model, screen hierarchy, visual scale, cache, likely data provider, mouse support, and the shape of a future backend. That gave Codex room to make implementation choices without asking it to invent the product.

The first prompt made a program. Feedback made the product.

The first commit already contained the end-to-end skeleton. The useful work happened afterward: run it, notice something odd, describe the evidence, let the agent inspect it, and keep the correction small enough to verify. The repository now records 66 prompt notes through the v0.3.0 release and the follow-up dependency and animated-cover update.

1. 1

   Choose the medium

   A follow-up challenged the initial language choice: Rust or Go instead of Python? Rust won because Ratatui offered precise cell and canvas rendering, Tokio handled background sync, and bundled SQLite kept distribution to one native binary.

2. 2

   Replace obvious fakes

   The first demo exposed synthetic ticker IDs and suspicious alternating gains and losses. The next pass kept simulated values but paired them with real SEC-catalog issuer identities and independent seeded returns. Demo data became useful without pretending to be live.

3. 3

   Debug the terminal, not an abstraction

   Mouse reports, Braille chart guides, font fallback, and delayed input all behaved differently inside a browser terminal. Screenshots and exact symptoms led to SGR mouse support, terminal-stable guide glyphs, contrast tests, and a shutdown sequence that drains input before returning to the shell.

4. 4

   Let constraints change the architecture

   A shared no-key market-data proxy sounded convenient. Provider terms made public redistribution unsafe, so the live path stayed bring-your-own Alpaca credentials. Cloudflare R2 serves only the independently derived SEC issuer catalog; prices and news stay behind the user's chosen provider.

One native client, several deliberately narrow boundaries

Specific observations beat impressive prompts

The sessions ran through chatcode.dev, but the platform was mostly the workbench: a persistent browser terminal where Codex could inspect the repository, run tests, and continue after the laptop closed. More interestingly, that environment surfaced real xterm and browser-font behavior that a local mock would have missed.

• Point at evidence. “The cursor drifts farther to the right” was more actionable than “the chart looks wrong.”
• Ask for the trade-off. The Rust-or-Go question produced a decision the repository could explain, not just a language switch.
• Keep judgment human. Licensing, visual taste, security boundaries, and what counts as honest demo data still needed explicit choices.
• Turn a fix into a guardrail. Rendering bugs became tests; ambiguous SEC share structures became fail-closed catalog rules.

You do not need to arrive with a perfect specification. A concrete first picture and the confidence to say “that is not what I meant” are enough to start. The project became precise one observation at a time.

The demo needs no account and no market-data key

Clone the project and run its deterministic offline demo. It generates simulated prices for 900 real SEC-catalog issuer identities, keeps demo and live databases separate, and labels the screen SIMULATED.

git clone https://github.com/chatcode-lab/stock-tui.git
cd stock-tui
cargo run --release -- --demo

Prebuilt binaries for Linux, macOS, and Windows are also attached to the GitHub releases. This is early, pre-1.0 software and not investment advice.