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 75 prompt notes through the v0.3.2 package-manager release, including trusted crates.io publishing and first-party Homebrew delivery.

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.

5. 5

   Make background work earn its requests

   A traffic audit found that an idle client refreshed far more than its visible screen required. Version 0.3.1 limits the five-minute cadence to current sector members, benchmark proxies, and favorites, and pauses it when the terminal forwards lost focus. Startup, catalog reconciliation, and explicit refreshes retain the broader discovery path.

6. 6

   Treat installation as part of the release

   Version 0.3.2 added crates.io, a maintained Homebrew tap, and native Debian packages. The work included clean installation checks, Intel and Apple Silicon validation, pinned artifact digests, and publishing paths that stop before their own publication when release identity or provenance does not match.

One native client, several deliberately narrow boundaries

The install path became part of the product

The v0.3.2 release has five checksummed platform archives and local amd64 and arm64 Debian packages. The macOS binaries cover Intel and Apple Silicon, use the hardened runtime, and are signed and accepted by Apple's notary service.

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.

Install it, then choose demo or live data

The quickest route on macOS or Linux is Homebrew. The deterministic offline demo needs no account or market-data key, generates simulated prices for 900 real SEC-catalog issuer identities, and labels the screen SIMULATED.

brew install chatcode-lab/tap/stock-tui
stock-tui --demo

With Rust 1.95 or newer, stock-tui can also be built from crates.io:

cargo install --locked stock-tui
stock-tui --demo

Checksum-verified Linux and Windows archives, signed and notarized Intel and Apple Silicon macOS archives, and local Debian packages are attached to the release. The public live-data path remains bring-your-own Alpaca credentials. This is early, pre-1.0 software and not investment advice.