displaying-images

Stars9

Forks1

UpdatedMay 8, 2026 at 00:24

Display images in the terminal using the Kitty graphics protocol via kitty-img. Use when the user asks to show, display, view, preview, or render an image file (PNG, JPG, GIF, SVG, etc.) in the terminal, or when you want to visually present a generated image.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

TrevorS

TrevorS/dot-claude

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

name	displaying-images
description	Display images in the terminal using the Kitty graphics protocol via kitty-img. Use when the user asks to show, display, view, preview, or render an image file (PNG, JPG, GIF, SVG, etc.) in the terminal, or when you want to visually present a generated image.

Image Display Skill

Display images inline in the terminal using the Kitty graphics protocol. Works in Ghostty, Kitty, and WezTerm. In tmux, uses direct pty writes to bypass DCS passthrough entirely.

Triggers: show image, display image, view image, preview image, render image, kitty-img, kitty protocol

Usage

Always use --popup when calling from Claude Code — it's the most reliable mode.

kitty-img --popup <image-file> [max-width-cols]

image-file — path to any image (PNG, JPG, GIF, SVG, WebP, etc.). ImageMagick handles conversion.
max-width-cols — display width in terminal columns (default: auto-fit to 80% of window)

Split pane mode (without --popup) also works but shows a title bar and dismiss prompt.

How It Works

In tmux (both modes): Writes Kitty escape sequences directly to the client tty, bypassing tmux entirely. No allow-passthrough needed.
Outside tmux: Renders the image inline at the cursor position via stdout.
Over SSH: Works transparently — the local terminal (Ghostty) does the rendering regardless of where the tmux session originated.
Aspect ratio: Only the column width is sent to the Kitty protocol (c=N). The terminal calculates the correct height from the image's native aspect ratio. Popup/pane sizing uses actual cell pixel dimensions from tmux.

Examples

# Show a screenshot (popup, auto-sized)
kitty-img --popup /tmp/screenshot.png

# Preview at a specific width
kitty-img --popup diagram.svg 40

# Split pane mode (has title + dismiss prompt)
kitty-img /tmp/screenshot.png

# Quick test that the protocol works
kitty-img-test

Requirements

Terminal with Kitty graphics protocol support (Ghostty, Kitty, WezTerm)
magick (ImageMagick) for format conversion and resizing
tmux 3.3a+ for popup/split pane modes

Limitations

Claude Code's Bash tool captures stdout, so images cannot render inline in Claude Code output. The tmux popup/split is the workaround.
Popup mode writes to the outer terminal pty — positioning is approximate.

More from this repository

same repository

syncing-claude-config

TrevorS/dot-claude

Sync this Claude Code config against new release notes — find config features added since the pinned baseline that this config should adopt. Use when Claude Code has been updated, when the user asks what's new / what changed / whether to adopt new settings or hooks, after a version bump, or when checking config currency against the latest release. Reports adoptable settings/hooks/env-vars/permissions as a risk-tiered proposal, then bumps the baseline. Do NOT use for auditing existing config quality, debugging hooks, or organizing rules — that is `maintaining-claude-code`.

2026-07-309

monitoring-ci

TrevorS/dot-claude

Monitor and watch GitHub Actions CI/CD pipeline runs in real time. Use when the user has pushed code and wants to watch the build, check CI status, see if tests passed, monitor a pipeline, or wait for a workflow run to complete. Also use after any `jj git push` or `git push` command. Reports pass/fail with failed job logs. Do NOT use for writing or editing CI workflow YAML files, optimizing CI config, or debugging CI configuration — only for monitoring active runs.

2026-07-309

cleaning-commit-history

TrevorS/dot-claude

Reorganize and clean up messy commit history on a feature branch into logical, reviewable commits. Use when cleaning up commits, preparing a branch for review, separating formatting from logic changes, fixing broken intermediate states, or squashing WIP commits.

2026-07-309

maintaining-claude-code

TrevorS/dot-claude

Audit and improve Claude Code hooks, rules, and settings.json. Use when adding/debugging a hook, organizing rules, auditing settings.json (permissions, env vars, stale flags), or deciding between hook vs skill vs rule vs CLAUDE.md. For SKILL.md authoring use the skill-creator plugin; for CLAUDE.md audits use the claude-md-improver plugin.

2026-06-019

executing-test-plans

TrevorS/dot-claude

Execute a structured test plan and emit a concise results document (JSON + Markdown). Use when running test plans, executing QA workflows, verifying acceptance criteria systematically, or producing test results documentation.

2026-06-019

searching-history

TrevorS/dot-claude

Search past Claude Code sessions to recall prior solutions, commands, fixes, and decisions. Use when the user references earlier work ("how did I fix", "last time we", "pick up where we left off", "a few months ago", "what was that … I set up", "didn't I once").

2026-06-019

name	displaying-images
description	Display images in the terminal using the Kitty graphics protocol via kitty-img. Use when the user asks to show, display, view, preview, or render an image file (PNG, JPG, GIF, SVG, etc.) in the terminal, or when you want to visually present a generated image.

Image Display Skill

Display images inline in the terminal using the Kitty graphics protocol. Works in Ghostty, Kitty, and WezTerm. In tmux, uses direct pty writes to bypass DCS passthrough entirely.

Triggers: show image, display image, view image, preview image, render image, kitty-img, kitty protocol

Usage

Always use --popup when calling from Claude Code — it's the most reliable mode.

kitty-img --popup <image-file> [max-width-cols]

image-file — path to any image (PNG, JPG, GIF, SVG, WebP, etc.). ImageMagick handles conversion.
max-width-cols — display width in terminal columns (default: auto-fit to 80% of window)

Split pane mode (without --popup) also works but shows a title bar and dismiss prompt.

How It Works

In tmux (both modes): Writes Kitty escape sequences directly to the client tty, bypassing tmux entirely. No allow-passthrough needed.
Outside tmux: Renders the image inline at the cursor position via stdout.
Over SSH: Works transparently — the local terminal (Ghostty) does the rendering regardless of where the tmux session originated.
Aspect ratio: Only the column width is sent to the Kitty protocol (c=N). The terminal calculates the correct height from the image's native aspect ratio. Popup/pane sizing uses actual cell pixel dimensions from tmux.

Examples

# Show a screenshot (popup, auto-sized)
kitty-img --popup /tmp/screenshot.png

# Preview at a specific width
kitty-img --popup diagram.svg 40

# Split pane mode (has title + dismiss prompt)
kitty-img /tmp/screenshot.png

# Quick test that the protocol works
kitty-img-test

Requirements

Terminal with Kitty graphics protocol support (Ghostty, Kitty, WezTerm)
magick (ImageMagick) for format conversion and resizing
tmux 3.3a+ for popup/split pane modes

Limitations

Claude Code's Bash tool captures stdout, so images cannot render inline in Claude Code output. The tmux popup/split is the workaround.
Popup mode writes to the outer terminal pty — positioning is approximate.