The format of a screen

View as Markdown Open in Claude Open in ChatGPT

A screen is two files in corpus/<agent>/screens/, with the same slug:

<slug>.screen: the exact bytes.
<slug>.yaml: the metadata and the expected result.

schema/screen.schema.json is the full definition. This page explains it.

The `.screen` file

It holds the exact output of tmux capture-pane -p. When the style matters, it holds the output of capture-pane -p -e, with SGR escape codes.
It is UTF-8, with LF line endings, and the trailing newline is kept.
Do not reformat it. An editor that strips trailing white space changes the screen without a sign. .editorconfig and .gitattributes prevent this.

The `.yaml` file

schema: 1
agent: claude                # equals the folder name; see the list below
agent_version: 2.1.309
valid_from: 2.1.251          # optional
superseded_by: null          # optional: the slug that replaces this screen
measured: 2026-10-24
capture: plain               # plain | styled
pane: {cols: 120, rows: 40}   # required for measured; optional when the size is not known
provenance: measured         # measured | measured-edited | derived
edits: []                    # measured-edited: one line for each edit
derived_from: hand-built     # derived: the source slug and what changed, or hand-built
description: >
  What the screen shows, and why it is in the corpus.
expect:
  state: PERMISSION          # IDLE | BUSY | PERMISSION | TRUST | DIALOG_OVER_BOX | NO_BOX | UNKNOWN
  dialog: question           # optional: permission | question | review | trust | none
  question: "Which colour?"  # only where the screen pins it
  options:
    - {n: 1, label: Red, selected: true}   # n is optional: some menus have no numbers
    - {n: 2, label: Blue}
  box_text: null
negative_control_for: null   # optional: the slug this screen must not be confused with
known_false_positive: false  # optional
known_false_positive_reason: null
facts: [7, 15]               # optional: the facts this screen pins

The agents

The agent field holds the folder name of the agent. The schemas allow these names:

Folder	Agent
`claude`	Claude Code
`agy`	Antigravity CLI
`codex`	Codex CLI
`copilot`	GitHub Copilot CLI
`gemini`	Gemini CLI
`cursor`	Cursor CLI
`opencode`	opencode
`qwen`	Qwen Code
`aider`	Aider
`amp`	Amp
`goose`	Goose
`crush`	Crush
`kimi`	Kimi Code CLI
`continue`	Continue CLI
`droid`	Factory Droid
`cline`	Cline CLI
`kilo`	Kilo Code CLI
`auggie`	Auggie
`openhands`	OpenHands CLI
`opencode2`	opencode 2
`kiro`	Kiro CLI
`junie`	Junie CLI
`codebuff`	Codebuff
`qoder`	Qoder CLI
`codebuddy`	CodeBuddy Code
`letta`	Letta Code
`neovate`	Neovate Code
`everycode`	Every Code
`iflow`	iFlow CLI
`vibe`	Mistral Vibe
`gptme`	gptme
`interpreter`	Open Interpreter
`grok`	Grok CLI

A new agent needs its name in schema/screen.schema.json and schema/coverage.schema.json. A name that is not in the list is a schema problem.

The states

State	Meaning
`IDLE`	A framed input box that waits for a message. A reader must prove this state. It must not give `IDLE` because no other rule matched.
`BUSY`	The agent works on a turn.
`PERMISSION`	A dialog waits for an answer: a permission, a question, or the review of a question. `dialog` tells them apart.
`TRUST`	The folder-trust question.
`DIALOG_OVER_BOX`	A dialog draws above a live input box, and the box keeps its frame.
`NO_BOX`	The agent has not drawn its input box yet.
`UNKNOWN`	A screen that the reader cannot read. A tool must send no key to it.

Provenance

Value	Meaning
`measured`	The bytes as tmux captured them.
`measured-edited`	Captured, then edited. Each edit has one line in `edits`, for example "path scrubbed to /work/example".
`derived`	Hand-built, or made from another screen. `derived_from` names the source and the change.

Known false positives

Some expected states are wrong on purpose. A dialog quoted in a reply looks like a dialog, and a reader that reads it as a dialog sends no key, which is safe. A rule that reads it as an idle box would also read a real dialog as an idle box. Such a screen has known_false_positive: true and a reason. Do not "fix" it.