Skip to main content
The Lacanians
Open Source7 min read

Terminal UIs as Text: Giving Coding Agents Something to Check

A coding agent cannot see a terminal screen, so terminal UI work becomes guesswork. Tuimark turns the UI into text and every frame into JSON, which gives agents an edit, dump, check loop and gives you golden tests.

A

Abdul Hamid Achik

The Agent Cannot See the Screen

Ask a coding agent to build a terminal interface and it will write plausible code. It will pick widths, nest containers, and report that the layout works. It has no way to check, because a terminal screen is pixels in someone else’s window.

So the agent guesses. A column overflows by two cells, a list scrolls past its selection, a panel collapses to zero rows, and nobody finds out until a human runs the program. The agent’s confidence tells you nothing here.

The pattern is general. When an agent builds something it cannot observe, the work reduces to unverified claims, which is the failure we described in Done Is Not Verified. The fix is not a smarter agent. It is giving the agent a machine-readable view of the thing it is building.

We built that view for terminals. Tuimark is an open-source view language where the interface is text, and every rendered frame can be printed as JSON.

What Tuimark Is

Structure lives in .tui (XML). Style lives in .tcss, a reduced CSS. Data is JSON, and behavior is named actions such as on:select="open". A Go runtime interprets those files, lays out an integer cell grid, paints Unicode, and dumps a snapshot of the result.

Here is the structure of an inbox, from the repo’s examples/inbox/app.tui, trimmed:

<tui version="1" theme="dark">
  <style src="theme.tcss"/>
  <keymap>
    <bind keys="q" action="quit"/>
    <bind keys="enter" action="open" when="#inbox:focus"/>
  </keymap>
  <screen id="main" focus="#query">
    <col id="app">
      <row id="body">
        <col id="sidebar">
          <input id="query" bind="query" placeholder="search" on:submit="search"/>
          <list id="inbox" each="tickets as item" key="item.id"
                bind="selected" on:select="open">
            <item><row>
              <text class="muted">{item.id}</text>
              <text>{item.title}</text>
            </row></item>
          </list>
        </col>
      </row>
    </col>
  </screen>
</tui>

The matching stylesheet, also from the repo, is plain enough for an agent to edit without a manual:

#sidebar { width: 32; border: single; border-color: $border; }
#detail  { flex: 1; border: single; border-color: $border; }
list:focus { border-color: $focus; }

@media (max-cols: 80) {
  #body { layout: column; }
  #sidebar { width: 100%; height: 8; }
}

What It Is Not

The boundaries matter more than the feature list, because they are what keep an agent on track. The README states them as rules the runtime holds to.

  • Interpreted, not compiled. The runtime reads .tui files at run time. Nothing generates Go code.
  • A closed catalog. Tags and CSS properties are a fixed set. An unknown one is a diagnostic, not a new widget.
  • Integer cells. One unit is one terminal cell. There is no px, em, or vh.
  • No logic in markup. No expressions, filters, or function calls. Markup gets literal values, {path} interpolation, each, and if.

Each rule removes a way for the agent to be creative in the wrong place. Run validate on an invented tag and the runtime refuses it:

error V001 x.tui:3:5 /screen/card unknown tag <card>

Try a pipe filter inside a binding and you get V003, with the message “markup has no expressions”. If the view needs a computed value, it goes in the data and the host computes it. The agent gets a precise error with a position, instead of a screen that silently looks wrong.

The Edit, Dump, Check Loop

The core idea is a loop an agent can run without eyes. It edits the three files, then asks the runtime what the frame looks like:

tuimark validate app.tui --data sample.json
tuimark dump app.tui --data sample.json --cols 80 --rows 24 --format json

The JSON has a grid (one string per row, exactly what the screen shows), a nodes list with the geometry of every element, and an errors list. A node looks like this:

{ "id": "inbox", "tag": "list", "x": 1, "y": 3, "w": 78, "h": 5,
  "scroll": { "y": 0, "h": 5 } }

Now the agent can answer concrete questions. To check the text, it reads grid. To check that a panel has the right size and position, it reads x, y, w, and h. To check where focus started, it reads focus. These are checks, not impressions.

Because the runtime is deterministic, the same inputs produce the same frame every time. That makes the dump evidence in the sense we used in the verification post: a specific observation from a specific run.

What a Dump Catches

Dumping the repo’s inbox example at 60 columns by 12 rows produced a real warning:

warning L006 app.tui:28:13 /screen/col/row/col/box/scroll
scroll gets 0 rows on its scroll axis but has content there, so it can
never show it; give it a cells, %, or fr height, or more room in its parent

At that size the detail pane is squeezed to two rows and its scroll area is 0 rows tall. Nobody asked for that, and a screenshot-free agent would never have noticed. The grid also shows ticket ids and titles touching, as in t-12login loop on staging, because the example’s row sets no gap. The dump shows both problems without a human looking at anything.

Golden Tests for Free

A dump is a snapshot, so it is also a test fixture. A golden is a dump saved to a file and committed. tuimark test renders the view again and compares.

The manifest lists which views and sizes to pin:

[
  {
    "name": "inbox",
    "file": "ui/app.tui",
    "data": "ui/sample.json",
    "sizes": ["80x24"],
    "json": ["80x24"]
  }
]

We ran tuimark test --update to write goldens, then edited the stylesheet: sidebar width from 32 to 24, and the media query from 80 columns to 60. The test failed at once:

FAIL inbox 80x24 (json): line 53: want "      \"w\": 80,", got "      \"w\": 24,"
FAIL inbox 80x24 (text): line 3: want "┌────…────┐", got "┌──────────────────────┐┌─────…"

The next agent that touches this view gets a failing test and a readable diff, not a surprise. The same manifest can pin a frame after key input, and --update refuses to overwrite a JSON golden unless the new one only adds members. A moved node fails the update until a human passes --allow-breaking.

The Lesson Beyond Terminals

Tuimark is one instance of a rule we apply to every agent system we build: before asking an agent to produce something, ask what the agent will observe to know it worked.

For a terminal UI, nothing observable existed, so we made text the source of truth and JSON the readout. For a database, it might be a query result. For a browser flow, it might be a recorded spec, which is the argument in Looks Correct Is Not Is Correct.

Three habits transfer to any project:

  1. Close the vocabulary. An agent that can only use known parts produces errors you can read.
  2. Make state a deterministic dump. Same input, same output, in a format a script can diff.
  3. Commit the dump as a test. Today’s verified state becomes tomorrow’s regression check.

If you build tooling for agents, this is where we do our own agent and AI systems work. For a first look, the Tuimark docs and the GitHub repo cover the language, the CLI, and the Go API. The docs also describe tuimark agents, which prints a briefing to paste into your agent’s instructions.

A

Abdul Hamid Achik

Founder and lead engineer at The Lacanians. Abdul builds production software, developer tools, and local-first systems from Guadalajara for teams worldwide.