Skip to content

hashgraph-online/awesome-codex-plugins / plugins/bnc4vk/codex-tui-proof/skills/validate-tui-in-codex

validate-tui-in-codex

Verified

Visually validate an interactive CLI or terminal UI in Codex's in-app browser using a real local PTY, fixed rendering, keyboard interaction, screenshots, and session evidence. Use for TUI layout changes, terminal menus, colors, prompts, resize behavior, keyboard flows, or proof-of-work where Codex would otherwise reach for Computer Use or a desktop terminal. Do not use for desktop-terminal-emulator-specific behavior or ordinary non-interactive command output.

FileKindSize
SKILL.mdskill md5.7 KB
agents/openai.yamlconfig228 B
references/evidence-contract.mdmarkdown2.4 KB

references/evidence-contract.md

View on GitHub
# Codex TUI Proof evidence contract

Use this reference when automating the harness or reporting validation evidence.

## Ready signal

The runner prints one machine-readable line:

```text
TUI_PROOF_READY {"url":"http://127.0.0.1:<port>","host":"127.0.0.1","port":<port>,"command":"...","cwd":"...","cols":100,"rows":30,"autostart":true}
```

Use the returned URL verbatim.

## HTTP endpoints

- `GET /api/health`: readiness, harness version, and current status.
- `GET /api/evidence`: concise validation state without the terminal transcript.
- `GET /api/state`: complete live state plus the retained ANSI transcript.

`/api/evidence` includes:

- `contractVersion`
- `harnessVersion`
- `status`, `sessionId`, and `pid`
- `command` and `cwd`
- `cols` and `rows`
- start/stop/exit metadata
- `recordingPath`
- input/output byte counters
- current error, if any

## Stable browser selectors

- `command`: configured command input
- `cwd`: working-directory input
- `cols`, `rows`: geometry inputs
- `restart`, `stop`: lifecycle buttons
- `status`: session status
- `session-label`: active command/session identifier
- `dimensions`: authoritative PTY size
- `terminal`: xterm container
- `metrics`: live input/output byte counts
- `recording`: JSONL recording label

The xterm accessibility layer exposes the active keyboard target as `textbox "Terminal input"`.

## WebSocket messages

The WebSocket accepts only an exact same-origin connection from the allocated `127.0.0.1` page.

Client to server:

- `{ "type": "input", "data": "..." }`
- `{ "type": "resize", "cols": 100, "rows": 30 }`
- `{ "type": "start" | "restart", "command": "...", "cwd": "...", "cols": 100, "rows": 30 }`
- `{ "type": "stop" }`

Server to client:

- `state`, `output`, `metrics`, `reset`, and `error`

## Recording

Each session writes JSONL under `runtime/recordings/`. Records contain an ISO timestamp, `direction` (`meta`, `input`, or `output`), data, and lifecycle/resize fields where applicable.

Input records contain typed characters. Never enter secrets during a proof session.

## Minimum acceptance criteria

1. Browser status is `running` for the target command and cwd.
2. Browser dimensions equal the requested PTY geometry.
3. At least one requested keyboard or lifecycle interaction is observed in resulting TUI state.
4. `/api/evidence` agrees with the browser state.
5. A screenshot comes from the controlled in-app-browser tab.
6. No Computer Use or desktop terminal was invoked.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall