Skip to main content
plugin CX Codex

codex-tui-proof — Claude Code plugin: TUI checks and install

codex-tui-proof is a Claude Code plugin for checking terminal UIs in Codex's browser with keyboard input and screenshots. It runs from a TUI validation request.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-tui-proof@awesome-codex-plugins
Open on GitHub

What codex-tui-proof does

codex-tui-proof starts a local PTY and renders it in Codex's in-app browser for repeatable terminal UI checks. The workflow verifies the command, working directory, terminal dimensions, and session state, then sends the requested key sequence, captures a screenshot, and records structured session evidence. It leaves desktop automation out of the process: Computer Use, Terminal.app, iTerm, and desktop keyboard control are refused.

The setup needs the ChatGPT desktop app with the Browser plugin enabled, a Codex CLI release that provides codex plugin commands, Node.js 20 or newer, and npm. The initial proof run installs three pinned runtime dependencies through npm. The HTTP and WebSocket services bind to 127.0.0.1; session recordings contain terminal input and output, so secrets must not be entered into a proof session. Shell operators such as pipes and redirects are unsupported.

What it helps with

  • inspect a local TUI at fixed terminal dimensions
  • run a keyboard flow through an interactive CLI
  • attach a screenshot and session record to a UI check
  • reproduce a broken input path and run the proof again
  • verify the PTY command, working directory, and geometry

Example prompts for the agent

  • Visually check this TUI at 100x30 and attach screenshots with $validate-tui-in-codex.
  • Inspect the command palette, choose an item, and attach proof with $validate-tui-in-codex.
  • Reproduce the broken keyboard flow, fix it, and rerun the proof with $validate-tui-in-codex.

How to install codex-tui-proof

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-tui-proof@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-tui-proof

How do I install codex-tui-proof in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then run /plugin install codex-tui-proof@awesome-codex-plugins.

What does codex-tui-proof do?

The plugin launches a local PTY and opens it in Codex's browser. It drives keyboard actions, checks the session state, takes a screenshot, and emits structured evidence.

What does codex-tui-proof require?

It requires the ChatGPT desktop app with Browser enabled, a Codex CLI release with codex plugin commands, Node.js 20 or newer, and npm.

Source text

codex-tui-proof · MIT
# Codex TUI Proof

Visual validation for real terminal UIs, inside Codex, without taking over the desktop.

![Codex TUI Proof running OpenCode in the in-app browser](assets/opencode-final.png)

Codex TUI Proof launches a real local PTY, renders it in a deterministic browser terminal, and gives Codex a repeatable workflow for keyboard interaction, screenshots, and session evidence. It is built for developers shipping interactive CLIs and TUIs who want visual proof alongside code changes.

## Install

Requirements: the ChatGPT desktop app with the **Browser** plugin enabled, a Codex CLI release with `codex plugin` commands (verified with `0.144.2`), and Node.js 20 or newer with npm.

```sh
codex plugin marketplace add bnc4vk/codex-tui-proof
codex plugin add codex-tui-proof@codex-tui-proof
```

Start a new Codex task so the skill is loaded, then ask:

```text
$validate-tui-in-codex visually validate this TUI at 100x30 and attach screenshots.
```

The first proof installs three locked runtime dependencies locally. Later runs start immediately. The plugin has been tested on macOS; the runtime also handles Windows and Unix shells, with CI covering macOS, Windows, and Linux.

### Install from the desktop app

Open **Settings → Plugins**, choose **Add more**, and enter:

```text
https://github.com/bnc4vk/codex-tui-proof.git
```

Install **Codex TUI Proof** from that marketplace and start a new task.

## What Codex does

1. Starts the bundled localhost PTY bridge in the integrated terminal.
2. Opens the exact allocated `127.0.0.1` URL in Codex's in-app browser.
3. Checks command, working directory, terminal geometry, and session status.
4. Drives the requested keyboard flow and observes the resulting state.
5. Captures a controlled-tab screenshot plus structured session evidence.
6. Stops the local harness when validation is complete.

The workflow explicitly refuses to fall back to Computer Use, Terminal.app, iTerm, or desktop keyboard automation.

## Why not a headless TUI test?

Headless tools are excellent for assertions. Codex TUI Proof covers a different gap: a coding agent needs to see and interact with the rendered TUI while it works, then hand the developer reviewable visual evidence.

| Capability | Codex TUI Proof | Headless TUI test | Desktop automation |
|---|---:|---:|---:|
| Real local PTY | Yes | Varies | Yes |
| Visible in Codex | Yes | Usually no | Indirectly |
| Deterministic geometry | Yes | Yes | Varies |
| Screenshot evidence | Yes | Varies | Yes |
| Leaves desktop untouched | Yes | Yes | No |
| Structured session evidence | Yes | Varies | No |

This is not a new terminal emulator or a replacement for ttyd, shell-use, Termless, VirtUI, or VHS. See the [prior-art review](docs/prior-art.md) for the architecture decision.

## Agent-facing contract

The launcher emits one machine-readable readiness line:

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

Codex uses that URL verbatim. Stable browser selectors and JSON endpoints expose status, dimensions, command, working directory, byte counts, and the local recording path. The full contract is in [evidence-contract.md](skills/validate-tui-in-codex/references/evidence-contract.md).

Useful prompts:

```text
$validate-tui-in-codex check the command palette, select an item, and attach proof.

$validate-tui-in-codex verify this resize fix at 80x24 and 120x40.

$validate-tui-in-codex reproduce the broken keyboard flow, fix it, and re-run the proof.
```

## Direct launcher and diagnostics

Codex normally runs these commands for you:

```sh
node scripts/tui-proof.mjs doctor

node scripts/tui-proof.mjs start \
  --command "opencode" \
  --cwd "/path/to/worktree" \
  --cols 100 \
  --rows 30 \
  --port 0
```

`--port 0` prevents collisions between concurrent tasks. Run `node scripts/tui-proof.mjs --help` for the complete launcher syntax.

Commands are parsed into an executable and arguments and are not interpolated into a shell command. On Windows, a fixed PowerShell bridge resolves executables while keeping the parsed arguments separate. Shell operators such as pipes and redirects are intentionally unsupported; put complex setup in a reviewed script and launch that script instead.

## Privacy and security

- The HTTP and WebSocket server bind only to `127.0.0.1`.
- There is no telemetry, account, hosted service, or remote data store.
- Session recordings include terminal input and output. Do not type secrets into a proof session.
- The target executable runs directly with the launcher's local user permissions and may access the network if it normally does.
- The first run contacts npm to install the three versions pinned in `runtime/package-lock.json`.

Read [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md) before using the plugin with sensitive projects.

## Development

```sh
npm ci --prefix runtime
npm run check --prefix runtime
npm test --prefix runtime
```

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and use [SECURITY.md](SECURITY.md) for vulnerability reports.

## License

[MIT](LICENSE) © 2026 Ben Cohen

© Ben Cohen · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Testing and QA →

From the same set391

The whole set →
context-guard context-guard is a Claude Code and Codex plugin that preserves requirements and verification evidence in long Codex tasks. It restores open items after context compaction and checks evidence before marking work complete. CX Codex ★ 1,596repo stars codex-attachment-manager codex-attachment-manager is a Claude Code plugin that manages image history in Codex tasks. It selects attachments for the next message and searches them by description. CX Codex ★ 1,596repo stars codex-claude-council codex-claude-council asks Claude and ChatGPT the same question, then lets them debate across multiple rounds until both reach agreement. CX Codex ★ 1,596repo stars codex-usage-and-resets codex-usage-and-resets is a Claude Code plugin that reports Codex weekly usage, pace, and reset expirations. It estimates whether the allowance will last until the next reset. CX Codex ★ 1,596repo stars codex-tasklist codex-tasklist is a plugin for Codex CLI that creates a live task panel, saves state to SQLite, and switches to tmux when native terminal panels are unavailable. CX Codex ★ 1,596repo stars codex-skin-pack-installer The codex-skin-pack-installer plugin stages and checks public-safe Codex skin packs from GitHub releases. Use it when a custom background, artwork, and a visible restore path matter. CX Codex ★ 1,596repo stars codex-rg-guard codex-rg-guard is a Claude Code plugin that narrows broad repository searches through a budgeted MCP tool. It selects files before returning bounded line matches. CX Codex ★ 1,596repo stars codex-reviewer codex-reviewer runs a secondary audit over AI-authored plans and pull requests. Catches architectural blind spots and unverified code before merge. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open