DEV Community: Stefanie Jane 🌠

Get Loopy! Act, React, Iterate Until We Love It

Stefanie Jane 🌠 — Sat, 25 Jul 2026 00:12:19 +0000

For the past week, an agent has been rewriting the retrieval system inside my memory engine. So far it's made a deterministic scorer, run dozens of experiments, kept the good ideas and ditched the failed ones. I wrote one prompt at the start and have made a few calls along the way (insert coin to continue). The loop is doing the rest, and it isn't even close to done.

At 3:30 every morning, another model wakes up to a standing instruction I wrote once and never send. It reads what my agents captured yesterday, decides what's worth keeping, promotes the confident findings into a knowledge graph, and routes the uncertain ones to me. Nobody is awake. The system is prompting itself.

And in one five-day stretch last month, a PR babysitter I built ran a thousand agent sessions against my open pull requests. Poll, classify, dispatch, fix, learn, repeat. Tiny models for watching, frontier models for fixing. As agents and humans review code, we react immediately and update PRs automatically.

This article will show you a few techniques I use everyday for large scale agentic engineering.

🌀 The Name Finally Caught Up

In June the term loop engineering landed. Peter Steinberger put it in twelve words: "you shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents." Addy Osmani named the practice a day later and gave it an anatomy; O'Reilly republished the essay two weeks after that, which is how you know a term has officially arrived. Boris Cherny, who created Claude Code, summed up the vibe: "I don't prompt Claude anymore."

The lineage is clean. Prompt engineering is about what we tell the model. Context engineering is how we can make the model create and improve those prompts. Loop engineering is about what happens between runs: the trigger, the feedback signal, the state that carries forward, and the rule that decides when it stops.

This post is the third act of a trilogy I have apparently created! In January I wrote about engineering the context. In May I wrote about the operating system underneath my prompts: a contract, a skill library, a memory graph. This one is about what happens when that operating system starts running itself.

One receipt for how convergent this moment is: while mining my own session archive for this post, an agent found the original wish for my memory consolidation loop, timestamped April 4. Verbatim: "i really want a dream mode for claude code. like something that reviews all our conversations regularly." Two months before anyone named the practice. If you've been working seriously with agents, you've been converging on the same ideas. The name doesn't unlock anything; it just gives us a shared vocabulary.

There is a bit of craft here.

⚡ Act → React: The Core Mechanic

At their core, every agentic loop is the same three-beat cycle:

Act. The agent does something real: edits code, runs an experiment, drives a browser, opens a PR.
Observe. The world answers with a signal: a test result, a metric, a screenshot, a review verdict, CI going green or red.
React. The loop, not a human, feeds the signal back into the agent's context, and the next act is shaped by it.

Mermaid source

flowchart LR
    A["⚡ Act"] -->|"edit · run · drive · ship"| O["👁 Observe"]
    O -->|"tests · metrics · screenshots · CI"| R["🔄 React"]
    R --> G{"stop condition true?"}
    G -->|"no, go again"| A
    G -->|"yes"| D["💎 done"]
    S[("state carrier: ledger · graph · git")] -.-> A
    R -.-> S

That third part is really the thing. A prompt is a one-shot context delivery: you curate what the model sees, it acts, done. A loop is a context engine. Every iteration curates what the next iteration sees, automatically, from the results of the last one. The agent is feeding itself. Then we think about the loops around the loops.

Which means the quality of a loop is exactly the quality of four components:

The feedback signal. What does the loop observe after acting? A signal that's fast, deterministic, and dense beats an expensive vague one every single time, because the loop consumes it on every iteration. Tests are great signals. Typed metrics are great signals. "The page looks better than it did before" is not a signal, but "the page's style matches the style guide perfectly" is .

The state carrier. What survives between iterations? The model's context window doesn't. It fills, it compacts, it's gone when the session ends. Loops that compound carry state outside the model: a findings ledger, a journal file, a task board, a knowledge graph, git history itself. The agent forgets; the repo doesn't.

The stop condition. When is it done? "When it's good" is not a stop condition. A testable predicate is: tests green, findings count at zero, metric above threshold, budget exhausted, human says ship.

The safety rails. Budgets, cooldowns, whatever you need to make sure everything stays on track and nothing goes crazy and lights your wallet on fire.

Everything that follows is the same four components rearranged.

🧪 The Eval Loop: An Agent Running Real Science

The best loop I've run this year is still running while I write this: an experiment campaign against Sibyl, my memory engine, on the LongMemEval v2 benchmark, because v1 is saturated to the point that a good score is table stakes rather than signal. A week in, it already shows what act → react looks like when the feedback signal is engineered instead of vibed.

Our goal: improve our benchmark scores, without cheating.

The agent's first move was the one that made everything else work: it built itself a super simple scorer. Instead of asking an LLM judge "did this retrieval look good?" on every iteration (slow, noisy, expensive), it wrote a script that checks whether the known-correct answer literally appears in the assembled context. That check is cheap, exact, and instant, and every configuration got a real number in seconds:

exposure 14/23 ( 60.9%)  phrase-hit  66.7%  ctx  36.9K avg
exposure 15/23 ( 65.2%)  phrase-hit  69.7%  ctx  35.8K avg
exposure 16/23 ( 69.6%)  phrase-hit  69.7%  ctx  47.8K avg

Then the loop proper. The plan said six experiments; the results kept suggesting new ones, and the list has grown to dozens so far, because that's what loops do. Each experiment ran in the background and could crash and resume where it left off, and the agent slept until a results file (or a stack trace) showed up to react to.

The surprise came from scoring two things separately: whether search found the right memories, and whether the layout actually got them onto the page. Search was already finding 82.6% of the answers; the layout only got 65.2% of them in front of the model. The bottleneck wasn't search at all. It was page layout. I would not have guessed that, and neither did the agent: the loop measured its way there.

One change looked like a clear win. Instead of shipping it, the loop did the thing that separates engineering from enthusiasm: it ran the same experiment three more times and compared results question by question. The win evaporated: the average had been sitting still while individual questions churned underneath it. Single runs lie. Five plausible improvements were retired this way, each with receipts.

We got as far as we could without an LLM, but the idea survived: have a tiny, fast model write a short digest of every memory as it's stored, about fifteen cents for the whole corpus. Replicated effect: +6.67 points, nine questions better, two worse. Then it flunked its first test on a different kind of data, the agent worked out why (the digest was reading fields that didn't exist there), fixed it, and passed the rerun.

Dozens of commits have landed and the campaign is still running as this post goes up. The eval loop is rewriting the system it's evaluating, live.

The transferable lessons, because your version of this won't be a memory benchmark:

Build the cheap scorer first. One hour spent making feedback deterministic pays back on every iteration. LLM judges belong at the end of a loop, not inside it.
Make iterations resumable. Experiments that can crash and resume turn an overnight failure into a delay instead of a loss.
Replicate before you believe. N=1 results are noise wearing a costume.
Retire hypotheses with receipts. A loop that only confirms is a yes-machine. Five documented rule-outs bought the credibility of the one win.

🎭 Visual Verification: The Loop Got Eyes

The loop upgrade that still feels like magic: agents can see now, and seeing closes feedback cycles that used to require a human on every iteration.

The modern setup: the agent drives the running app in a real browser, the rendered surface itself rather than the test suite. It navigates, clicks, fills forms, and screenshots. The screenshot is the observe beat. The agent compares what it sees against the acceptance criteria, fixes, re-renders, looks again. For UI work I'll write something like "the cards align to an 8px grid, the hover state doesn't shift layout, dark mode holds contrast" and let the loop iterate itself there, screenshot by screenshot. A year ago this was "make the change, describe it to me, I'll look." Now the agent is the one looking, and it catches the 2px misalignment I would have missed.

The same pattern runs end-to-end tests as a loop signal: drive the app, assert on what actually rendered, feed failures back as context. And it composes with everything else in this post. A review loop where the reviewer also drives the app catches a class of bug no diff-reader ever will.

One rule keeps these loops honest, learned the expensive way and now written into my skill library: perf and visual loops need an objective signal before iteration two. Loops judged by the next screenshot become random walks. The screenshot is the sensor, not the standard. Pin the standard first (named acceptance criteria, a reference design, a metric, a golden snapshot) and let the screenshots measure against it. An agent iterating toward "looks better" will happily wander forever, each iteration convincingly justified.

When the surface is one the agent can't observe, the first move is building the connector, because most "unobservable" surfaces are just missing a driver. Terminals get automation harnesses like ghostty-automator or cmux that drive keystrokes and read the screen back. Machines beyond the laptop get an agent over SSH. A drawer full of Android devices becomes a sensor array with an MCP server like droidmind pushing input and pulling screenshots from every one of them. Each connector converts a blind spot into a feedback signal, permanently, for every loop you build afterward.

And when the surface genuinely can't be instrumented (how a terminal feels, the light coming off actual hardware), the loop still doesn't end. The human becomes the sensor: hand them a pre-registered expected outcome and a discriminating tell, and you're still running act → react. You've just got a slower sensor with better taste.

🔮 Review Loops: Convergence You Can Graph

The loop I run most often is cross-model review to convergence, and the state carrier is what makes it more than "ask another model twice."

The shape: one model produces an artifact. A spec, a plan, a diff. A different model reviews it adversarially. The findings go into a ledger that travels between rounds: every finding verbatim, the claimed fix, the commit SHA of the fix. The next round's reviewer gets the ledger and two jobs: verify each claimed fix actually landed, and hunt for new problems the fixes introduced. The artifact and its ledger are the loop's memory. The agent is feeding itself its own review state.

You track convergence numerically, and the numbers tell you things. A recent infrastructure plan of mine converged over twelve rounds:

17 → 9 → 8 → 4 → 3 → 2 → 1 → 1 → 4 → 1 → 1 → PASS

See round nine? Four new findings after two quiet rounds, because the round-eight fixes broke new ground. Convergence isn't monotonic, which is exactly why you graph it instead of trusting your sense that "it's probably fine now." Another spec went 19 → 6 → 4 → 2 → 0 in five rounds. When the trend stalls or oscillates, the loop is telling you the remaining findings are matters of judgment, and judgment is the human's job.

The community has been circling the simplest form of this for a while: implement, review, fix, repeat, sometimes with a hook that re-feeds the same prompt until the work is done. Fine as far as it goes. But the naive version has a failure mode that only shows up in production use: not all review loops should stop the same way, and treating them uniformly either burns tokens or ships defects. What I've converged on:

Code review: cap the re-litigation, not the rounds. Three visits to the same finding means you're in an argument, not a review. But rounds that keep surfacing new confirmed defects keep going.
Spec review: iterate until you love it. Spec defects are the most expensive class of defect there is, so convergence is the only exit. My standing instruction to the loop is literally "iterate until we love it."
Fix passes: pre-declare a file budget. Review-fix loops are a monotonic scope ratchet; every round wants to touch a few more files. I've watched one hit 8 rounds and 63 files before we re-anchored it to six. Now the budget gets declared before round one.

Two independence rules, both non-negotiable. The implementer never self-assigns PASS, because the model that wrote the code is too kind grading its own homework, and so is the same model re-reading it. And a verdict is pinned to a SHA: any commit after the reviewer's pass voids the pass. Warm-resuming the same reviewer speeds up fix-round convergence; a fresh-context reviewer does final certification precisely because it inherits nothing.

🛠️ The Babysitter: 1,785 Sessions in Five Days

Vigil is a PR babysitter I built this spring: an agent system that watches my open pull requests and does whatever they need next. In its first real production window it ran 1,785 agent sessions in five days, every one of them against my real PRs.

The loop: pollers watch GitHub (my PRs every 30 seconds, the wider radar every 60). State changes get classified by a five-state machine (hot, waiting, ready, dormant, blocked) and classified events go to a cheap triage agent with a five-cent budget that routes to specialists: a fixer with a fifty-cent budget and 15 turns, a responder for review comments, a rebaser, an evidence gatherer. A fixer pushes a commit, the next poll sees fresh CI, triage re-routes. The loop continues until the PR hits READY.

Mermaid source

flowchart LR
    GH[("GitHub")] -->|"poll 30s / 60s"| SM{"five-state machine"}
    SM --> T["🧭 triage · 5¢"]
    T --> FX["🔧 fixer · 50¢ · 15 turns"]
    T --> RS["💬 responder"]
    T --> RB["🌿 rebaser"]
    FX -->|"push → fresh CI"| GH
    RS --> GH
    RB --> GH
    T -.->|"3 strikes · irreversible"| H["👤 you"]
    GH -->|"on merge"| LN["📚 learning agent"]
    LN -.->|"patterns → future prompts"| T

What the architecture diagram doesn't show: the loop logic is maybe a fifth of the code. The rest is safety rails.

Per-agent turn caps and dollar budgets, per run.
Event dedupe with a five-minute window, plus a 45-second cooldown per event type, because GitHub will happily tell you the same thing four times.
A concurrency gate so two agents never work the same PR simultaneously.
Prompt fingerprinting that flags when an agent is about to ask the same question it asked five minutes ago. That's the observability hook for loop detection.
Escalation: three consecutive failures on the same thing and it stops looping and pings the human.
Auto-approve for everything except the irreversible set: push, merge, branch delete. Reversible actions flow; irreversible ones queue for me.

There's also a second, quieter loop stacked on the first. On every merge, a learning agent extracts patterns into a knowledge file ("this reviewer usually asks for type annotations on public APIs, confidence 0.70"), and new patterns start at 0.50 confidence and gain +0.10 on each reconfirmation. The whole file gets injected into future triage and fix prompts. Every PR makes the next one smoother. The loop's output has become the loop's context, and that's the move that compounds.

To be fair, you no longer need to build any of this yourself just to get your PRs babysat. Codex and Claude are both solid PR watchers out of the box now, and with newer models you can hand one an entire stack: a PR goes up, a bot review posts feedback, human engineers post theirs, and the agent reads it all as it lands, updates the PR, and replies to the comments with a summary of what changed. What the off-the-shelf version doesn't ship is everything around the loop: the budgets, the dedupe, the learning file, and the queue of irreversible actions that waits for a human.

If you build one loop this year, build a babysitter for something you already poll by hand that nobody has productized yet. The design pressure is fantastic: every safety rail above exists because its absence produced a specific, memorable mess.

🌙 Loops That Feed the Loops

The layer above all of this is where it gets properly recursive: loops whose output is the context machinery itself.

Consolidation runs nightly. Sibyl's dream cycle wakes at 3:30am, reads what my agents captured during the day, and applies a hard policy: findings it's confident about promote into the knowledge graph automatically, anything it's unsure of queues for me, and duplicates and stale entries get archived. Every agent's tomorrow-context is being curated by an unattended model run tonight, gated by policy.

Forgetting is a loop too. Every recall an agent makes stamps usage counters on the entities it retrieved. A nightly decay job consumes those counters: memory that gets used survives, memory that doesn't fades and eventually archives. Reads are the training signal for retention. The knowledge graph is under continuous selection pressure from the swarm's actual behavior. I don't garden it; the usage gardens it.

And once a season, the big one. In July I pointed one prompt at my entire session archive: "review the last few months of Claude and Codex sessions and mine all the patterns and good stuff that worked." What ran: five chained workflows, 208 subagents, two hours and fifty-three minutes. Sixty-two readers worked through distilled versions of ~600 sessions (about 8GB of raw transcripts), pulled out 1,883 findings, merged them into 221 patterns, and then eleven editor agents with adversarial verifiers rewrote my skill library and my agent contract from the evidence of their own use. The loop system audited itself and shipped the patch.

A solid finding, mined from months of my own sessions: "Rules don't self-enforce at generation time; checkpoints do." Written by an agent, about agents, from watching agents. The instruction you put in the prompt is a hope; the verification you build into the loop is a guarantee.

That's the full stack of self-feeding: the eval loop improves the memory engine, the memory engine improves every agent's context, the agents' transcripts improve the skills, and the skills improve the loops. Each layer's exhaust is the next layer's fuel.

Mermaid source

flowchart LR
    E["🧪 eval loop"] -->|"improves"| M["🔮 memory engine"]
    M -->|"curates"| C["🗂 every agent's context"]
    C -->|"produces"| T["📜 session transcripts"]
    T -->|"rewrite"| S["🧠 skills + contract"]
    S -->|"sharpen"| E

🎯 Proof at Scale: Bun's Rust Rewrite

Everything above ran on my laptop against my projects. If you want evidence that the same discipline holds at three orders of magnitude more scale, May was happy to oblige: Bun rewrote itself from Zig to Rust. 535,496 lines of Zig across 1,448 files became a 1,009,272-line Rust diff in eleven days, built by 64 Claude agents running continuously, for about $165,000 in API-priced tokens. Jarred Sumner's estimate of the manual alternative: three engineers with full codebase context, about a year.

Jarred published the core of the system as pseudocode, and it's the act → react cycle verbatim:

let task
while ((task = todoList.pop())) {
  const result = task()
  const feedback = await Promise.all([review(result), review(result)])
  await apply(feedback, result)
}

Act, observe twice in parallel, react. And every component from the anatomy section is there at industrial strength:

The feedback signal is the whole story. Bun's test suite is written in TypeScript, which means it's independent of the runtime's implementation language: 1,386,826 expect() calls on Linux x64 alone, roughly 60,000 tests per platform, functioning as a conformance suite for the port. When the tests pass, the port is correct, and no LLM judge has to opine. During the compiler-error phase (16,000 errors at the start), the loop was literally "run cargo check, group the output by file, save the errors to a file, fix all the compiler errors within that crate." Deterministic, dense, cheap.

The state carrier was built before the loop ran: three hours producing a PORTING.md (600 lines of Zig-to-Rust pattern mappings, with hard constraints like no tokio, no async/await, because Bun owns its own event loop) plus a LIFETIMES.tsv mapping the ownership of every struct field. Both documents got their own adversarial review before any code generation started. Context engineering feeding loop engineering.

Independence was structural. One implementer, two adversarial reviewers per task, and the roles never blur: "The implementer doesn't review. The reviewer doesn't implement." Reviewers got only the diff and were told to assume the code is wrong. Every line of the million-line diff crossed two adversarial readers at a peak throughput of 1,300 lines per minute.

The rails were physical. Four git worktrees with 16 agents each, so shards couldn't touch each other's files. Agents banned from git stash, git reset, anything that doesn't commit a specific file. The stop condition had integrity teeth: 100% of the suite passing with zero tests skipped or deleted, because a loop that's allowed to delete failing tests will absolutely delete failing tests.

The most instructive moment is the failure. Mid-run, agents started interpreting "get all the crates to compile" as "stub out the functions": the classic false-victory pathology, at scale. The fix wasn't hand-editing stubs. It was one prompt edit, and the stubbing stopped fleet-wide. Jarred's summary of the methodology is the cleanest one-line definition of loop engineering I've seen: a million-assertion test suite, adversarial review, and "when something does go wrong, fixing the process that generates the code instead of hand-fixing the code."

Not everyone applauded. Zig's creator called it "unreviewed slop", and 6,502 commits in eleven days is a real review-debt question no matter how adversarial the machine reviewers were. The preconditions were also unusually good: an expert who knew every corner of the codebase steering daily, and a test suite that took years of runtime development to accumulate. That's the lesson, not a caveat to it. The rewrite took eleven days because the feedback signal took years. Your test harness is the asset your future loops will spend.

💎 The Craft: What Separates a Loop from a while(true)

Distilling everything above, plus a couple of years of expensive mistakes, into the principles I'd actually defend:

Size the loop to the work. Loop engineering earns its keep in two places: greenfield scope too big to hold in your head (new builds, ports, benchmark campaigns) and toil that recurs forever (PR queues, nightly digests). A small task or a routine debugging session doesn't want a harness; the setup never pays back, and the ceremony slows down work you could have just done. The exception is the verify loop, which is free and belongs everywhere.

Type your stop conditions. Different loop species stop differently, and using the wrong stop rule is the classic failure:

Loop species	Stop rule	Why that one
Spec review	Convergence: iterate until you love it	Spec defects are the most expensive class there is
Code review	Re-litigation cap: three visits to one finding	New confirmed defects keep rounds alive; arguments don't
Research	Yield: a wave that surfaces nothing new is the last	Count-based stops miss the tail in both directions
Digests	Cron: the schedule is the stop	The job is cadence, not convergence
Exploration	Budget: turns or dollars, pre-declared	Open-ended search needs a wall set before it starts
Self-re-prompting	A completion predicate that can only be emitted truthfully	"Blocked cleanly, with receipts and a runbook" is terminal; fake-done is not

Engineer the feedback signal. Deterministic beats judged, dense beats sparse, and cheap beats expensive, because the loop pays the cost on every iteration. The geometry sweep worked because the scorer was exact; vigil works because CI and GitHub state are unambiguous; visual loops work when the acceptance criteria are named before iteration one.

Carry state outside the model. Ledgers, journals, knowledge graphs, git history. The context window is a scratchpad, not a database. Every loop that compounds does it through external state; every loop that plateaus is usually re-deriving what it knew yesterday.

The dominant failure mode is stopping early, not running away. Everyone fears the runaway loop; in practice the pathology you'll actually fight is the agent quietly declaring victory: the plan-only exit, the false "all done!" on an empty turn, the wrap-up reflex as context fills. I spent a research cycle on this while building a swarm harness, and the design answer is a watchdog that distinguishes stalls from stops: re-prompt on stall, replan on no-progress, and break the loop only on a repeated failure signature. Pair it with turn and dollar budgets and you've bounded both tails.

Independence is structural, not aspirational. The implementer never self-assigns PASS. Verdicts pin to SHAs. Final certification gets fresh context. None of this is about model quality; it's about the same conflict-of-interest logic we already apply to humans.

Budgets and rails will save you at some point. Get these right so you don't wake up to a huge bill and mess.

🌸 Start With One Loop

You don't need my stack. You don't even need a special harness: every loop in this post runs on stock agent CLIs, Claude Code or Codex, sometimes Pi or OpenCode, with small scripts and cron holding the loops together. The agents are ordinary sessions; the engineering is in what surrounds them, and all of it is portable. This is a good order:

1. The verify loop (you probably already do this). Edit → test → fix, every two or three edits, enforced as loop structure rather than discipline. Throw in agent-browser or another tool to give the agent visibility into it's own output

2. The review-to-convergence loop (this week). Next spec: have a different model review it, keep a findings ledger, fix, re-review, and track the count. Watch it converge, or watch round nine surprise you. Stop conditions per the craft section: convergence for specs, re-litigation caps for code.

3. The scheduled digest (this month). One recurring report you currently assemble by hand: last week's merges, your open review queue, error trends. Cron a session, give it a fail-closed preflight, gate delivery behind a fact-check pass. This is your intro to loops that run when you're not watching, with training wheels: worst case is a bad report to yourself.

4. The babysitter (when the polling pain is real). Pick the thing you check compulsively (a flaky CI pipeline, that long-running db migration, your PR queue) and wrap a poll → classify → act loop around it, with the full rail kit: budgets, cooldowns, dedupe, escalation, irreversible-actions-queue-for-human.

5. The memory loop (when the others are humming). Scheduled consolidation of your sessions into recallable knowledge, with a confidence gate between the unattended run and what your future agents get to see. This is the one that makes the other four compound.

And measure the loop, not the vibes: iterations to convergence, cost per iteration, unverified-claim rate, escalation rate, and how often the loop's stop condition fired versus you pulling the plug. A loop earning its keep shows up in those numbers within a week; a loop that doesn't gets deleted.

🦋 The Part That Stays Human

Osmani ends his essay warning against cognitive surrender, the temptation to stop having judgment once the automation feels smooth. It's the right warning. Every loop in this post keeps a human where it counts: I pick the hypotheses the eval loop tests, approve the pushes vigil queues, review what the dream cycle isn't sure about, and make the judgment calls the review ledger converges toward. The loops removed the toil of re-prompting, not the steering. If anything, they concentrated the job into its highest-leverage form: designing feedback systems and exercising taste at their decision points.

Two years ago the craft was writing the perfect prompt. One year ago it was engineering the context. This spring it was the contract, the skills, and the memory. Now the context engineers itself, on a schedule, from the results of its own actions, and the craft moved up another level: act, react, repeat, with you designing the loop and keeping the judgment.

Don't just prompt. Engineer the loop. Iterate until you love it. 💜

Originally published at hyperbliss.tech. Follow me on GitHub and Bluesky.

The Terminal Renaissance: Designing Beautiful TUIs in the Age of AI

Stefanie Jane 🌠 — Fri, 10 Apr 2026 00:23:12 +0000

Something shifted.

It wasn't sudden. More like tectonic plates moving under the industry while everyone watched the AI hype cycle. But the evidence is hard to ignore. Claude Code now authors 4% of all public GitHub commits , 135,000 a day, doubling month over month. 69% of developers keep a terminal open at all times. OpenCode, a terminal-native AI coding agent, hit 95,000 GitHub stars in two weeks. Ghostty, a GPU-accelerated terminal emulator, went nonprofit because its creator believed the terminal mattered enough to protect from acquisition.

The terminal isn't having a nostalgia moment. It's having a platform moment.

And nobody's talking about how to design for it.

⚡ The Three Forces

Three things happened at once, and the compound effect is bigger than any of them alone.

AI agents chose the terminal. Claude Code, Codex CLI, Gemini CLI, OpenCode:
every serious AI coding tool lives in the shell. Not because terminals are trendy, but because the terminal is where execution happens. IDE extensions suggest code. Terminal agents write code, run tests, read logs, fix errors, and commit. The terminal became an AI runtime nobody intentionally designed, and it turns out to be a really good one.

Modern tooling raised the floor. A generation of Rust and Go tools quietly
replaced the Unix standard library with versions that are faster, prettier, and more intuitive. ripgrep over grep. bat over cat. eza over ls. fd over find. yazi over ranger. zoxide over cd. lazygit over raw git. atuin over Ctrl+R. And tools like ChromaCat, which turns any terminal output into animated gradient art with plasma patterns, aurora effects, and 40+ themes, proved that the terminal could be genuinely beautiful, not just functional. The terminal got a glow-up that had nothing to do with AI; it just got better as a daily environment.

Terminal emulators became premium products. Ghostty renders at 500fps with
native GPU acceleration and platform-native UI. Kitty pioneered an inline image protocol that lets terminals show things. WezTerm ships a built-in multiplexer. Rio runs on WebGPU. The modern terminal baseline is true color, font ligatures, Unicode everywhere, and rendering performance that puts some web apps to shame.

Put them together: more developers spending more time in terminals that are more capable than ever, building with frameworks that make terminal UIs genuinely enjoyable to create.

So where's the design language?

📖 The Missing Manual

Web developers have Material Design, Apple's Human Interface Guidelines, WCAG accessibility standards, and a research tradition going back decades. Mobile developers have platform-specific HIG documents, accessibility mandates, and component libraries that enforce consistency.

Terminal developers have... vibes.

I went looking for the equivalent. Here's what I found:

clig.dev: a solid CLI design guide that explicitly excludes TUIs: "Full-screen terminal programs are niche projects; very few of us will ever be in the position to design one."
Base16 / Tinted Theming: a color system with 230+ palettes. Covers color only. Nothing on layout, interaction, navigation, or component patterns.
A 1983 ACM paper on terminal interface design. The last (and essentially only) academic work on the subject.
awesome-tuis: the most-starred TUI resource list on GitHub. It's a catalog of apps. Zero design resources.

There is no HIG for terminal applications. No accessibility standard. No cross-framework design system. No academic research tradition. The closest thing is library documentation for individual frameworks, useful but framework-specific and focused on how to build, not what to build.

This gap isn't just an oversight. It's a massive opportunity. Terminals are a medium with their own affordances (information density, keyboard-first interaction, spatial memory, graceful degradation across connection quality) and they deserve design thinking that's native to those strengths, not borrowed from the web.

What follows is my attempt to start filling that gap. Not theory: lessons from building five production TUI applications across two frameworks, with a design system that spans all of them.

🏗️ Designing for 80 Columns

The first thing you learn building terminal UIs: every cell matters in a way that pixels don't. A web developer can throw a 32px margin on something and it disappears into the layout. In a terminal, a single wasted column is a percentage of your real estate. The constraint shapes everything.

🧱 Layout as Architecture

Terminal layouts aren't just arrangements; they're architectures that determine how users build mental models of your app. After building five apps and studying 23 exemplar TUIs, I've found that almost every successful terminal app falls into one of seven patterns:

Persistent Multi-Panel: Everything visible at once, panels in fixed
positions. lazygit, btop, and Unifly all use this. The magic is spatial consistency: users learn that "network traffic is top-right" and their eyes go there automatically. You never rearrange panels without explicit user action. The user's spatial memory is the navigation.

Miller Columns: Three columns showing parent, current, and preview. yazi and
ranger use this for file navigation. The insight: hierarchical data has a natural horizontal flow. You see where you came from (left), where you are (center), and where you're going (right). Elegant for anything tree-shaped.

Drill-Down Stack: Browser-like navigation into increasingly specific views.
k9s does this beautifully for Kubernetes (cluster → namespace → deployment → pod → container → logs), with :resource jumps for power users. The pattern for deep hierarchies where showing everything at once would be chaos.

Widget Dashboard: Independent, self-contained widgets in a grid. btop and
bottom take this approach for system monitoring. Each widget owns its own data lifecycle and rendering. Good when the relationship between data is "these are all about the same system" rather than "these are all about the same item."

IDE Three-Panel: Sidebar, main content, and detail/output. Iris Studio,
harlequin, and most development tools use some variant. The layout metaphor is: navigate (left), work (center), inspect (right). Tab bars give the main panel multiple personalities.

Overlay/Popup: Appears over the shell, does one thing, disappears. atuin and
fzf embody this. No state between invocations. The terminal equivalent of a modal dialog, summoned when needed, gone when done, never disrupting your scrollback.

Header + Scrollable List: Fixed header with stats, scrollable data below,
function bar at the bottom. htop and tig. The oldest pattern and still one of the most effective for any "view a list of things with summary stats" use case.

The choice isn't arbitrary. When I built Unifly (a network dashboard), persistent multi-panel was obvious: network state is best understood all at once, with your eyes learning where each metric lives. When I built Iris Studio (an AI git workflow), IDE three-panel was the right call, because you're working on one thing at a time but need navigation and context flanking the main content.

Picking the wrong layout is like picking the wrong data structure. Everything downstream gets harder.

🎯 Seven Principles

I've codified the design patterns that work across all seven layout types into principles. I won't enumerate them as a numbered list; that's not how they work in practice. Instead, they're threads that run through every decision:

Spatial consistency is the foundation. Panels don't move. Tabs stay in
order. The user builds a mental map of your app in the first minute and navigates by location memory after that. Every time you shuffle the layout, you reset their spatial model to zero.

Keyboard-first, mouse-optional means every feature is reachable without a
mouse, but mouse support isn't an afterthought either. The reason: terminal power users are keyboard people, but beginners discovering your app will click. Support both; optimize for keys.

Progressive disclosure is how you avoid the "wall of keyboard shortcuts"
problem. Three tiers: a footer bar showing the 3-5 most important keys (always visible), a ? help overlay with the full keybinding reference (on demand), and complete documentation for everything else. Beginners see the floor. Experts find the ceiling. Nobody reads a manual to get started.

Semantic color means color carries meaning, not decoration. Green means
success. Red means danger. Yellow means caution. If you stripped all color from your app and it became unusable, your design is broken. Color should reinforce information hierarchy that's already established through layout, typography, and symbols. More on this shortly.

Async everything is non-negotiable in 2026. Never freeze the UI. File
operations, network calls, AI generation: all background tasks with progress indicators. The user should always be able to press Esc and get back to a responsive interface. A TUI that hangs is a TUI that gets killed.

Contextual intelligence means your interface adapts to what the user is
doing right now. Keybindings change when focus moves between panels. The status bar reflects current state. Help shows shortcuts that are actually available in this context. The UI earns trust by always being accurate about what's possible.

Design in layers is the principle I wish someone had told me on day one.
Start with monochrome: is the app usable with no color at all? Then add 16 ANSI colors: is the hierarchy readable? Then layer in true color: is it beautiful? Each tier is independent. Your app works on a monochrome SSH session and looks stunning in Ghostty. That's not a tradeoff; it's a design discipline.

⌨️ The Vim Question

One pattern that emerged across every framework and every app I built: vim keybindings are the terminal lingua franca.

Not because every terminal user runs vim. But because j/k for up/down, h/l for left/right, / for search, ? for help, g/G for top/bottom, and Esc to go back is the most information-dense navigation vocabulary ever designed. It's six keystrokes that handle 80% of navigation. And it's muscle memory for exactly the audience that builds and uses TUIs.

I structure keyboard interaction in four layers:

L0 (Universal): Arrow keys, Enter, Escape, q to quit. Shown in the footer. Anyone can use this.
L1 (Vim motions): j/k/h/l, /, ?, :. Also shown in the footer. Terminal natives expect this.
L2 (Actions): Single mnemonic keys: d for delete, s for stage, r for refresh. Discoverable through the ? help overlay.
L3 (Power): Composed commands, macros, configuration. Documentation only. The ceiling for experts who've invested the time.

Each layer is invisible until the user reaches for it. That's progressive disclosure applied to keyboard interaction.

🎨 Color as Information Architecture

Color in a terminal is a resource, not a paintbrush. You have a constrained palette compared to the web, a wildly unpredictable rendering environment (users run every terminal emulator and theme combination imaginable), and an audience that may be looking at your app over SSH on a 16-color connection.

🌈 The Three-Tier Model

The golden rule: usable at 16 colors, beautiful at true color.

Your app encounters terminals in three capability tiers:

16 ANSI colors: The foundation. These are the colors the user's terminal
theme controls. When you say "red," the terminal decides what red looks like. This means your reds match their theme. The upside: automatic coherence. The downside: no fine control. Design with named ANSI colors and your app blends into any terminal. This is your SSH-over-a-bad-connection baseline.

256 colors: Extended palette with fixed colors. You gain control but lose
theme coherence. Your specific shade of purple will look the same on every terminal, which means it may clash with their background. Use sparingly for emphasis; don't build your entire palette here.

True color (24-bit): Full control. 16 million colors. This is where you make
it beautiful. But always remember: it's an enhancement layer over a 16-color foundation, not a replacement for one.

Detection is straightforward: check $COLORTERM for truecolor or 24bit. Check $TERM for 256color. Respect $NO_COLOR unconditionally: if it's set, strip all color. This isn't just accessibility; it's professional courtesy.

🏷️ Semantic Color Slots

The insight that changed how I think about terminal color: define colors by function, not appearance.

Instead of "this panel border is #e135ff," it's "focused panel borders use accent.primary." Instead of "errors are #ff6363," it's "errors use status.error." A semantic layer between your code and your colors.

Here's the vocabulary I use across all five apps:

text.primary: Main body text. Off-white on dark backgrounds.
text.muted: Secondary information, metadata, timestamps. Noticeably dimmer.
text.emphasis: Headers, focused items. Bright, bold.
bg.base → bg.surface → bg.overlay: Three background layers, each ~5-8% lighter. Creates depth without borders.
accent.primary: Your brand color. Interactive elements, focused borders.
accent.secondary: Supporting interactions. Secondary highlights.
status.success / .warning / .error / .info: Exactly what they sound like.
git.staged / .modified / .untracked: Domain-specific tokens for git apps.
diff.added / .removed: Domain-specific tokens for diff views.

When your colors have semantic names, your entire app becomes theme-swappable overnight. Change the values behind the names; every screen updates instantly. I proved this across five apps with 20 different themes, same codebase, completely different personalities.

🔧 Theming as Infrastructure

This is where most TUI developers stop: they pick some hex codes, scatter them through the codebase, and ship one look. Changing anything means grepping through 50 files.

I got tired of this after the second app. So I built Opaline, a token-based theme engine for Ratatui that implements the semantic color model as actual infrastructure.

The pipeline:

Palette (raw hex colors) → Tokens (semantic names that reference palette) → Styles (composed foreground + background + modifiers) → Gradients (multi-stop color interpolation)

Each layer references the one below it. Tokens like text.primary resolve to palette entries like gray_50. Styles like keyword compose a foreground token with bold. Gradients interpolate between palette entries for progress bars and visual effects.

The result: 20 builtin themes, including five SilkCircuit variants (Neon, Soft, Glow, Vibrant, Dawn), plus Catppuccin, Dracula, Nord, Rose Pine, Gruvbox, Tokyo Night, and more. Every theme is validated against a contract test suite: 40+ tokens must be defined, 18+ styles must resolve, 5 gradients must interpolate correctly. Users can write their own themes as TOML files. Runtime switching costs nothing.

The bigger lesson isn't about Opaline specifically. It's that theming is infrastructure, the same way a design system is infrastructure for the web. If you want visual consistency across multiple apps, or you want to support user customization without chaos, you need a resolution pipeline with semantic indirection. Hex codes in source files is a phase, not a strategy.

✨ SilkCircuit: A Terminal Design Language

To make the theme system concrete, I designed SilkCircuit as a cohesive visual identity for terminal applications. Not "use my colors," but "here's what a complete terminal design language looks like."

Electric Purple (#e135ff): Brand, emphasis, focus states
Neon Cyan (#80ffea): Interaction, file paths, tech elements
Coral (#ff6ac1): Accents, hashes, constants
Electric Yellow (#f1fa8c): Warnings, timestamps, attention
Success Green (#50fa7b): Confirmations, additions, online states
Error Red (#ff6363): Danger, deletions, offline states

Five variants prove the system works: Neon is electric and high-contrast. Soft is muted and comfortable. Glow adds bloom-like emphasis. Vibrant is saturated and bold. Dawn is a warm light theme. Same semantic slots, completely different energy. The design language is the mapping from meaning to color, not the colors themselves.

🚀 Five Apps, Two Frameworks

Theory is cheap. Here's what I actually learned by shipping.

📊 Unifly: The Dashboard

Unifly is a real-time network management dashboard for Ubiquiti UniFi controllers. Eight screens of live data: WAN traffic charts, device health, client lists, firewall rules, topology maps, event streams, historical analytics. Built in Rust with Ratatui.

The design lesson: information density is a feature, not a problem. Every
cell on screen earns its place. WAN bandwidth charts use a dual-layer technique : HalfBlock area fills for the smooth body with Braille character line overlays for the crisp edge. Traffic bars use fractional block characters (▏▎▍▌▋▊▉█) for sub-cell precision that makes terminal charts feel surprisingly smooth. Status indicators use semantic symbols: ● online, ○ offline, ◐ transitioning, ◉ pending adoption.

The architecture lesson: never poll. Unifly uses reactive streams,
tokio::watch channels that push data changes to the UI. The TUI doesn't ask "has anything changed?" on a timer. It gets told when something changes. The difference in responsiveness is visceral.

The product lesson: the dual-product pattern. Unifly ships as two binaries
from the same codebase: unifly (CLI for scripting and automation, JSON output, composable with pipes) and unifly-tui (interactive dashboard for humans). One core, two faces. The CLI lets you unifly devices --json | jq '.[] | select(.status == "offline")'. The TUI lets you explore the same data visually, drill into details, restart devices. Neither is better; they serve different workflows.

🤖 Iris Studio: The AI Workflow

Iris Studio is a six-mode AI-powered git workflow tool. Explore code semantically, generate commit messages, run code reviews, draft PR descriptions, create changelogs, write release notes, all from a three-panel TUI with a universal chat interface. Built in Rust with Ratatui.

The design lesson: modes need visual identity. Six modes could easily feel
like six apps wearing a trench coat. Consistent three-panel layout across all modes (navigate left, work center, inspect right) with mode-specific content keeps it unified. Shift+letter shortcuts for mode switching build muscle memory fast.

The architecture lesson: pure reducers make AI UIs predictable. When an AI
agent controls your UI, you need a state model you can reason about. Iris uses a Redux-style pure reducer where every state transition is a function from (state, event) → (new state, side effects). No I/O inside the reducer. Agent responses flow through the same event system as keystrokes. This makes the entire UI testable, debuggable, and auditable.

The interaction lesson: universal chat changes everything. Press / in any
mode and a chat overlay appears. Ask Iris to refine a commit message, explain a security finding in a review, or add detail to release notes, and it updates the content directly through tool calls. The AI isn't in a separate panel; it's accessible from anywhere you're working. Context follows you.

🔹 q: The Minimalist

q is a tiny Claude Code CLI built with TypeScript, Bun, and Ink (React for terminals). One letter, four modes: query (fire-and-forget questions), pipe (Unix pipeline citizen), interactive (full TUI), and agent (tool-using AI).

The design lesson: know when not to be a TUI. q's pipe mode is the
opposite of a rich interface: raw text output, no markdown formatting, no code blocks, no decoration. It's a perfect Unix filter. cat config.yaml | q "convert to json" > config.json. The discipline is in not rendering things when the context doesn't want rendering.

The framework lesson: React's mental model works in terminals. Ink maps
React's component model directly to the terminal. <Box flexDirection="column">, <Text color="cyan">, useState for state, useEffect for side effects. If you know React, you know Ink. The conceptual overhead is near zero. Claude Code itself is built on Ink, and that's not a niche endorsement.

👁️ Vigil: The Agent Orchestrator

Vigil is a PR lifecycle manager that dispatches AI agents to handle mechanical code review tasks. Card-based dashboard showing all your open PRs, six specialized agents (triage, fix, respond, rebase, evidence, learning), and a human-in-the-loop toggle that ranges from "approve every action" to "let agents run."

The design lesson: state machines need visual language. Vigil classifies PRs
into five states: hot (needs attention now), waiting (blocked on something), ready (good to merge), dormant (stale), blocked (can't proceed). Each state maps to a color, an icon, and a card style. The dashboard looks different when things are on fire versus when everything is calm. Color as information, not decoration.

The architecture lesson: the HITL/YOLO spectrum is a design decision.
Sometimes you want an agent to show you what it plans to do and wait for approval. Sometimes you want it to just handle things. The toggle between these modes is a UX feature, not a backend feature. It changes the entire interaction model of the dashboard. Building it taught me that human-AI control boundaries are UI design problems.

💎 Opaline: The Invisible One

Opaline is the theme engine underneath the other four. It doesn't have its own TUI. It is the reason the other four look cohesive.

What it taught: infrastructure is the unglamorous work that makes everything
else possible. Opaline is 20 builtin themes, a four-pass resolution pipeline, contract testing that validates every theme against a strict schema, and a ThemeSelector widget for drop-in theme pickers. Nobody sees it directly. Everyone benefits.

🛠️ Choosing Your Framework

I build in two frameworks, Ratatui (Rust) and Ink (TypeScript/React). Having shipped production apps in both, here's the actual decision guide:

Reach for Ratatui when your app is a dashboard, a monitor, or any data-heavy
view that runs for hours. Immediate-mode rendering means you describe the entire UI every frame and the framework diffs the terminal buffer for you. Zero garbage collection pauses. Runs beautifully over SSH. Netflix, AWS, and OpenAI all ship Ratatui apps in production. It's the right tool for btop-shaped problems.

Reach for Ink when your app is conversational, agent-driven, or benefits
from the npm ecosystem (syntax highlighting, markdown rendering, rich text). React's component model and hooks make state management familiar. Bun gives you fast startup and embedded SQLite. Claude Code is built on Ink. It's the right tool for chat-shaped problems.

What they share is more interesting than how they differ. Both ecosystems
converge on the same design patterns: unidirectional data flow (events → state → render), vim keybindings as the default navigation model, footer key hints with ? help overlays, semantic color systems, and action dispatch architectures. The framework is the least interesting choice you'll make. The design principles travel across both.

The real question isn't "Ratatui or Ink?" It's "what patterns does my app's data flow demand?" If you answer that well, the framework choice falls out naturally.

🎭 Playwright for Terminals

Here's the part nobody else is talking about.

AI coding agents can write TUI code all day. Claude Code, Codex, Gemini CLI: they'll generate Ratatui components, Ink React trees, Bubbletea models without breaking a sweat. But they have a fundamental problem: they're blind.

When Claude Code runs your TUI app, it gets stdout text. It cannot see the layout. It cannot verify that panel borders line up. It cannot check that j/k navigates correctly. It cannot tell if the status bar is rendering in the right color. It's building a visual interface without eyes.

This isn't a theoretical gap. Claude Code's Bash tool doesn't allocate a real PTY. Interactive programs hang. TUI apps corrupt terminal state. Gemini CLI shipped proper PTY support in October 2025; Claude Code still hasn't. The most capable AI coding agent in the world cannot interact with the category of applications we're building.

Web developers solved this problem years ago with Playwright and Cypress. The agent writes code, opens a browser, renders the page, inspects the DOM, takes screenshots, simulates interactions, and iterates. Test-driven development with eyes.

Terminals have nothing equivalent. Until now.

👻 ghostty-automator

I built ghostty-automator, a purpose-built IPC layer for Ghostty that exposes the terminal's actual state to external processes.

Not scraped text. Not regex-parsed ANSI escape sequences. Not tmux pane captures. The terminal emulator itself tells you, through structured data over a Unix socket, exactly what's on screen: every cell's character, foreground color, background color, bold/italic/underline state, and cursor position. The full semantic state of the rendered terminal.

A Python library wraps this with Playwright-style async ergonomics:

terminal.send("cargo run"): send a command
terminal.wait_for_text("Listening on"): wait for specific output
terminal.screen(): read what's on screen as text
terminal.cells(): read styled cells with color and formatting
terminal.screenshot(): capture a PNG
terminal.press("KeyJ"): send keystrokes
terminal.click(row=5, col=20): click at a position
terminal.expect.to_contain("Dashboard"): assert content

An AI agent skill wraps the whole thing so any Claude Code agent can install terminal automation in one command:

npx skills add hyperb1iss/ghostty-automator-python

The agent gets the full API: send commands, read screens, take screenshots, click cells, assert content. No MCP server configuration, no protocol wiring. Just install and go.

🔄 The Loop

Put the whole stack together and something remarkable happens:

The AI agent has design knowledge: a 3,000-line TUI design skill covering layout paradigms, color theory, interaction patterns, accessibility requirements, and anti-patterns ranked by real-world complaint frequency.

It has theming infrastructure: Opaline, so it can work with semantic colors and swap themes without touching the layout code.

It has frameworks: Ratatui and Ink, which it already knows how to use from training data and documentation.

And now it has eyes and hands: ghostty-automator, so it can run the app in a real terminal, see the rendered output, interact with it through keystrokes and mouse events, and verify that what it built matches what it intended.

The loop closes: design → build → run → see → fix → repeat. The same workflow web developers have had for years, finally available for terminal applications.

Most terminal automation approaches parse ANSI byte streams, capture tmux panes, or run headless emulators. ghostty-automator is different: purpose-built IPC where the emulator itself participates. No parsing, no scraping, no guessing. The terminal tells you its state because you asked in its native protocol.

This is Playwright for terminals. And I think it changes what's possible.

🔮 What Comes Next

The terminal stopped being the environment you escaped from. It became the environment you returned to, because it's actually better for how serious work happens now.

AI agents made it the control plane for software development. Modern frameworks made it beautiful. A generation of Rust and Go tooling made it a pleasure to live in. And now the infrastructure exists for those same agents to build, test, and iterate on terminal interfaces autonomously.

We have design principles for a medium that never had them. We have theming systems that bring design-system rigor to the terminal. We have frameworks in multiple languages that make building TUIs genuinely enjoyable. And we have an automation layer that gives AI agents eyes.

What we need now is more people building beautiful things. The terminal is a canvas. The tools are ready. The renaissance is here.

Projects mentioned in this post:

Opaline: Token-based theme engine for Ratatui (20 builtin themes)
Unifly: UniFi network management CLI + TUI
Git-Iris: AI-powered git workflow with Iris Studio TUI
q: The tiniest Claude Code CLI
Vigil: AI-powered PR lifecycle manager
ghostty-automator: Terminal automation IPC for Ghostty
ghostty-automator-python: Playwright-style Python API + AI agent skill
ChromaCat: Terminal colorization with animated gradient patterns and 40+ themes
SilkCircuit: Electric meets elegant — terminal design language and theme system
tui-design skill: 3,000-line TUI design knowledge base for AI agents

Frameworks:

Ratatui: Rust terminal UI framework (18.7K stars, used by Netflix/AWS/OpenAI)
Ink: React for the terminal (TypeScript)
Bubbletea: Elm architecture for Go TUIs (40K stars)
Textual: Python TUI framework with CSS-like styling

Further reading:

AI coding tools are shifting to the terminal, TechCrunch
Your terminal is an AI runtime now, Adel Zaalouk
Claude Code is the Inflection Point, SemiAnalysis
Building a TUI Is Easy Now, Hatchet
Learning From Terminals to Design the Future of User Interfaces, Brandur
TUI Design, Jens Roemer

✨ Originally published at hyperbliss.tech.

💜 If you dig this kind of work, consider sponsoring me on GitHub.

🦋 Find me on Bluesky and GitHub.