codex-preview

Codex Preview

Current release: 0.3.0 · changelog

A prompt-only terminal UI skill for Codex Desktop and Claude Code.

Turn a request or pasted data into braille charts, comparison bars, tables, state lanes, flows, and terminal wireframes. There is no Python runtime, renderer binary, package manager, or application code to install.

It is built for Codex Desktop's integrated terminal and Claude Code, with a copy-safe Unicode fallback for chat, Markdown, issues, and pull requests.

Why Use It?

Visualization should make a decision easier, not become another project.

• No runtime to explain: this is a skill, not a Python application. Install the instructions and ask Codex for a preview.
• See the shape quickly: spot trends, gaps, outliers, and state changes without opening a notebook, browser, or plotting stack.
• Think before building: sketch a dashboard, pipeline, or service flow in the terminal before writing frontend code.
• Keep the result portable: use color in the terminal and clean Unicode in Codex chat, documentation, issues, and reviews.
• Use the right amount of structure: templates keep bars, tables, labels, and flows readable without forcing a data format or local toolchain.

What It Does

• numeric series as braille charts and sparklines
• comparisons as aligned tables and microbars
• categorical history as state lanes or compact matrices
• sequential systems as box-drawing flows
• page and dashboard ideas as terminal wireframes

Codex renders the preview directly from the data in your prompt or workspace context. For very large datasets, ask it to sample or aggregate first and label the transformation.

Where It Works

Raw ANSI escape sequences are not intended for the Codex chat renderer. In chat, the geometry still works; open the integrated terminal when you want live color.

Quick Start

Codex Desktop on Windows

From PowerShell:

irm https://raw.githubusercontent.com/0xAnton1/codex-preview/main/scripts/install.ps1 | iex

Or from a cloned checkout:

.\scripts\install.ps1 -Target codex

The default destination is $CODEX_HOME\skills\codex-preview, or $HOME\.codex\skills\codex-preview when CODEX_HOME is unset.

Codex Desktop on macOS / Linux

curl -fsSL https://raw.githubusercontent.com/0xAnton1/codex-preview/main/scripts/install.sh | bash -s -- --target codex

Repo-local install

./scripts/install.sh --target codex --codex-dir "$PWD/.codex"

On Windows:

.\scripts\install.ps1 -Target codex -CodexDir (Join-Path $PWD '.codex')

Start a new Codex task after installation so the skill is discovered.

Claude Code

Install the Claude Code command into a project:

curl -fsSL https://raw.githubusercontent.com/0xAnton1/codex-preview/main/scripts/install.sh | bash -s -- --target claude --project-dir "$PWD"

On Windows:

.\scripts\install.ps1 -Target claude -ProjectDir $PWD

Then run /codex-preview in Claude Code with the preview request. The command and its project guidance use the same code-free terminal UI rules as Codex.

Use It In Codex

Invoke the skill directly:

Use $codex-preview to sketch a terminal dashboard for build health,
test coverage, deploy status, and recent latency.

Other useful prompts:

Use $codex-preview to show these values as a compact braille trend.
Use $codex-preview to map this pipeline as a terminal flow.
Use $codex-preview to compare these options in a TUI table.
Use $codex-preview to sketch this page as a terminal wireframe.

For a colored result, ask Codex to render in the integrated terminal. For a response you want to copy into Markdown, ask for monochrome Unicode.

Use It In Claude Code

After the project install, invoke the included command:

/codex-preview sketch a terminal dashboard for build health, test coverage,
deploy status, and recent latency

Claude Code receives the same surface rules: ANSI only in its actual terminal, and monochrome Unicode for content that will be copied to chat or Markdown. No Python, package manager, or renderer is required.

Is It Token-Efficient?

Usually, when the preview replaces a longer verbal explanation. Braille packs a curve into little horizontal space; short tables and state lanes make comparisons easy to scan.

ANSI is not automatically cheaper: every color sequence adds output. The efficient default is one small preview, monochrome or a few long color spans, sampled data, short labels, and no repeated frames.

This skill is token-light because the main instructions are concise and the richer examples are loaded only when they help. It does not claim a universal token saving; measure your own workload if cost matters.

How The Skill Works

Codex discovers the skill from its SKILL.md metadata. When a request clearly asks for a terminal/TUI visualization—or when you invoke $codex-preview—it chooses a compact visual form and renders it directly. Claude Code receives the equivalent project command at .claude/commands/codex-preview.md. references/patterns.md is available only when a richer layout pattern helps.

This is deliberately a code-free skill. The repository contains instructions, templates, metadata, and small shell-based installers—not a Python application. That makes the public repository easier to understand and keeps the installation independent of a programming language.

codex-preview/
├── SKILL.md
├── agents/openai.yaml
├── references/patterns.md
├── scripts/install.ps1
├── scripts/install.sh
├── VERSION
├── CHANGELOG.md
├── CLAUDE.md
├── .claude/commands/codex-preview.md
└── assets/

Design Boundaries

• Terminal-first does not mean terminal-only. Chat receives a portable Unicode fallback.
• The preview should expose structure, not pretend missing data exists.
• Explicit HTML, SVG, Mermaid, image, or interactive requests keep their requested format.
• Sixel and Kitty graphics require actual terminal and renderer support; the skill does not assume either.
• Color must reinforce labels and geometry, never become the only carrier of meaning.

Claude Code: First-Class Support

Claude Code is a supported installation target, not a best-effort compatibility layer. The installer adds a /codex-preview custom command and preserves existing project guidance. Its output contract is the same as Codex Desktop: terminal ANSI when supported; portable monochrome Unicode elsewhere.

./scripts/install.sh --target claude --project-dir "$PWD"

Or on Windows:

.\scripts\install.ps1 -Target claude -ProjectDir $PWD

The installer preserves an existing CLAUDE.md and writes the extra guidance to .claude/codex-preview-reference.md. It has no Python or other runtime dependency.

License

MIT