Terminal Screenshot

Name: Terminal Screenshot
Author: daymade

daymade/claude-code-skills

200 installs
1.3k repo stars
Updated August 4, 2026
daymade/claude-code-skills

Renders a terminal CLI program's colored output to a PNG so the result's colors and contrast can be seen.

About

Renders a terminal command's ANSI-colored output to a PNG image so the visual result can be judged instead of reading raw escape codes. A developer uses it to verify CLI color config like delta, bat, or theme changes.

Turns ANSI-colored output into a viewable PNG image
Enables real contrast and alignment judgement after color changes

Terminal Screenshot by the numbers

200 all-time installs (skills.sh)
Ranked #203 of 550 CLI & Terminal skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/daymade/claude-code-skills --skill terminal-screenshot

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/daymade/claude-code-skills/terminal-screenshot.svg)](https://skillselion.com/skills/daymade/claude-code-skills/terminal-screenshot)

Installs	200
repo stars	★ 1.3k
Last updated	August 4, 2026
Repository	daymade/claude-code-skills ↗

What it does

Renders a terminal CLI program's colored output to a PNG so the result's colors and contrast can be seen.

Files

SKILL.mdMarkdownGitHub ↗

Terminal Screenshot

Render the colored output of a terminal command into a PNG image, then read that image to judge the result visually.

Why this exists

When a command's output arrives as a tool result, Claude sees plain text plus raw escape codes like \x1b[48;2;92;30;34m — not the rendered colors. That makes it impossible to honestly answer "is the diff's add/remove contrast strong enough?" or "did this theme come out too dark?". Reading hex values is guessing. This skill turns the output into an image so the judgement is based on what a human would actually see on screen.

The method: capture, then render

Two separate steps. Keep them separate — that separation is the whole trick.

Step 1 — Capture full-fidelity ANSI to a file

Most CLIs drop or downgrade colors when they detect they're not writing to a real terminal (a pipe or a child process). Force full coloring and save to a .ansi file. The exact flag depends on the tool — recipes below.

The single most important rule: never let the renderer run the command for you. freeze --execute "git diff | delta" looks convenient but produces a degraded result — delta (and lazygit, and anything that probes terminal capabilities) runs inside freeze's child pty, detects a reduced environment, and silently drops its background blocks, line-number column, and header box. Capture in a normal shell first, render second.

Step 2 — Render the ANSI file to PNG, then read it

Use the bundled wrapper, which prefers freeze and falls back to a stdlib renderer + headless Chrome:

scripts/render_ansi.sh <input.ansi> <output.png> [background_hex]

Then read the PNG with the Read tool and judge the colors.

Background color must match the real terminal, or a dark theme verified on a white page looks wrong. On macOS with Ghostty:

ghostty +show-config --default | grep '^background'   # e.g. 282c34 (the default)

Pass it as #282c34. If unknown, a dark terminal is usually near #1d1f21–#282c34.

Capture recipes per tool

Pick a --width close to the real terminal (≈100–120) so wrapping matches.

Tool	Capture command (writes full-color ANSI)
delta (git diff)	`git --no-pager diff \
git diff (native)	`git -c color.ui=always --no-pager diff > /tmp/x.ansi`
bat	`bat --color=always --style=numbers <file> > /tmp/x.ansi`
eza	`eza -la --color=always --icons > /tmp/x.ansi`
ls (GNU)	`ls -la --color=always > /tmp/x.ansi`
ls (macOS/BSD)	`CLICOLOR_FORCE=1 ls -laG > /tmp/x.ansi`
ripgrep	`rg --color=always 'pattern' <path> > /tmp/x.ansi`
anything else	`CLICOLOR_FORCE=1 <cmd> > /tmp/x.ansi` or `<cmd> --color=always`, or wrap in a real pty: `script -q /dev/null <cmd>`

Note delta always emits its configured colors even to a file, so the only trap for delta is Step 1's rule (don't render it via freeze --execute).

Full example: verify a delta color change

# after editing [delta] colors in gitconfig, in any repo with a diff:
git --no-pager diff | delta --dark --line-numbers --width=110 > /tmp/diff.ansi
scripts/render_ansi.sh /tmp/diff.ansi /tmp/diff.png "#282c34"
# then: Read /tmp/diff.png and judge whether add/remove contrast is clear

TUI programs (lazygit, htop, top) — out of scope

Full-screen TUIs paint with cursor positioning, not a linear ANSI stream, so they can't be captured this way. To check a TUI's colors, verify the underlying piece in isolation — e.g. for lazygit's diff, render git diff | delta as above (lazygit calls the same delta config). For a true TUI screenshot, run it in a real terminal and capture the screen (a screencapture/computer-use task), not this skill.

Installing freeze (the preferred renderer)

freeze is charmbracelet/freeze — it renders ANSI to PNG/SVG/WebP with faithful background blocks and nice chrome.

Do not run `brew install freeze` — that installs an unrelated GUI app of the same name (a cask). The CLI lives in charmbracelet's tap or via go install:

# Option A — Homebrew tap (needs GitHub reachable)
brew install charmbracelet/tap/freeze

# Option B — go install (works behind a firewall via a Go module mirror)
GOPROXY=https://goproxy.cn,direct GOSUMDB=off \
  go install github.com/charmbracelet/freeze@latest
# binary lands in "$(go env GOPATH)/bin/freeze"

GOSUMDB=off is needed when the checksum database (sum.golang.org) is unreachable and go install hangs on "verifying module ... 504".

If freeze can't be installed, the wrapper automatically falls back to the bundled scripts/ansi2html.py (stdlib only) + headless Chrome — no extra dependency beyond a Chrome install. The fallback uses a fixed window size; widen --window-size in render_ansi.sh if output is clipped.

Bundled scripts

scripts/render_ansi.sh — render a captured .ansi file to PNG (freeze, else

Chrome fallback). This is the entry point; call it after Step 1.

scripts/ansi2html.py — stdlib ANSI→HTML converter used by the fallback path.

Handles 24-bit truecolor, 256-color, bold, and resets, preserving background color blocks (the part naive renderers drop).

Common pitfalls

Letting the renderer run the command (freeze --execute "delta …") →

degraded output. Capture in a normal shell first, render the file second.

Non-TTY strips color → force it (--color=always / CLICOLOR_FORCE=1 /

script -q /dev/null).

Wrong background color → a dark CLI theme rendered on a white page misjudges

contrast. Use the real terminal background.

Light/dark mismatch → if the terminal is dark, the CLI's colors must be its

dark variant. Verifying a light=true config against a dark terminal shows inverted, hard-to-read colors (and is itself the bug, not the renderer's fault).

`brew install freeze` installs the wrong (GUI cask) tool — use the tap or

go install.

#!/usr/bin/env python3
"""Render an ANSI-colored text file to a standalone HTML page (stdlib only).

Fallback renderer for when charmbracelet/freeze is unavailable. Parses the SGR
subset that real CLI tools emit: 24-bit truecolor (38;2;r;g;b / 48;2;r;g;b),
256-color (38;5;n / 48;5;n with xterm palette -> RGB), bold (1), and the resets
(0 / 39 / 49). Background color blocks (48;...) are preserved faithfully — that is
the whole point, since tools like delta encode add/remove as background blocks.

Usage: ansi2html.py <input.ansi> <background_hex> <output.html>
"""
import sys
import re
import html as H


def xterm256(n):
    """Map an xterm-256 palette index to an (r, g, b) tuple."""
    base = [
        (0, 0, 0), (205, 0, 0), (0, 205, 0), (205, 205, 0), (0, 0, 238),
        (205, 0, 205), (0, 205, 205), (229, 229, 229), (127, 127, 127),
        (255, 0, 0), (0, 255, 0), (255, 255, 0), (92, 92, 255),
        (255, 0, 255), (0, 255, 255), (255, 255, 255),
    ]
    if n < 16:
        return base[n]
    if n >= 232:
        v = 8 + (n - 232) * 10
        return (v, v, v)
    n -= 16
    r, g, b = n // 36, (n % 36) // 6, n % 6
    conv = lambda x: 0 if x == 0 else 55 + x * 40
    return (conv(r), conv(g), conv(b))


def rgb(t):
    return f"rgb({t[0]},{t[1]},{t[2]})"


def main():
    if len(sys.argv) < 4:
        sys.exit("usage: ansi2html.py <input.ansi> <background_hex> <output.html>")
    ansi_file, bg, out_html = sys.argv[1], sys.argv[2], sys.argv[3]
    fg = "#c5c8c6"  # default foreground for unstyled text on a dark background

    text = open(ansi_file, encoding="utf-8", errors="replace").read()
    parts = re.split(r"(\x1b\[[0-9;]*m)", text)
    cur_fg = cur_bg = None
    bold = False
    out = []
    for p in parts:
        if p.startswith("\x1b["):
            codes = p[2:-1].split(";")
            if codes == [""]:
                codes = ["0"]
            i = 0
            while i < len(codes):
                c = codes[i]
                if c in ("0", ""):
                    cur_fg = cur_bg = None
                    bold = False
                elif c == "1":
                    bold = True
                elif c == "22":
                    bold = False
                elif c == "39":
                    cur_fg = None
                elif c == "49":
                    cur_bg = None
                elif c == "38" and i + 1 < len(codes):
                    if codes[i + 1] == "2":
                        cur_fg = rgb((int(codes[i + 2]), int(codes[i + 3]), int(codes[i + 4])))
                        i += 4
                    elif codes[i + 1] == "5":
                        cur_fg = rgb(xterm256(int(codes[i + 2])))
                        i += 2
                elif c == "48" and i + 1 < len(codes):
                    if codes[i + 1] == "2":
                        cur_bg = rgb((int(codes[i + 2]), int(codes[i + 3]), int(codes[i + 4])))
                        i += 4
                    elif codes[i + 1] == "5":
                        cur_bg = rgb(xterm256(int(codes[i + 2])))
                        i += 2
                i += 1
        elif p:
            style = []
            if cur_fg:
                style.append(f"color:{cur_fg}")
            if cur_bg:
                style.append(f"background:{cur_bg}")
            if bold:
                style.append("font-weight:bold")
            esc = H.escape(p)
            out.append(f'<span style="{";".join(style)}">{esc}</span>' if style else esc)

    doc = (
        '<!DOCTYPE html><html><head><meta charset="utf-8"><style>\n'
        f"body{{margin:0;padding:18px;background:{bg}}}\n"
        'pre{margin:0;font-family:"JetBrains Mono",Menlo,Consolas,monospace;'
        f"font-size:15px;line-height:1.55;color:{fg};white-space:pre}}\n"
        "</style></head><body><pre>" + "".join(out) + "</pre></body></html>"
    )
    open(out_html, "w", encoding="utf-8").write(doc)
    print(out_html)


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
# Render a *captured* ANSI file to a PNG image.
#
# Prefers charmbracelet/freeze (faithful background blocks, line-number boxes,
# window chrome). Falls back to a zero-dependency stdlib HTML renderer +
# headless Chrome when freeze is not installed.
#
# IMPORTANT: feed this an ANSI file you already captured in a normal terminal
# (see SKILL.md "Step 1"). Do NOT rely on `freeze --execute` to run complex
# CLIs like delta/lazygit — they degrade inside freeze's child pty and drop
# background blocks / line numbers.
#
# Usage: render_ansi.sh <input.ansi> <output.png> [background_hex]
set -euo pipefail

ANSI="${1:?usage: render_ansi.sh <input.ansi> <output.png> [bg_hex]}"
OUT="${2:?usage: render_ansi.sh <input.ansi> <output.png> [bg_hex]}"
BG="${3:-#282c34}"
HERE="$(cd "$(dirname "$0")" && pwd)"

# Locate freeze: PATH first, then the default `go install` bin dir.
FREEZE="$(command -v freeze 2>/dev/null || true)"
if [ -z "$FREEZE" ] && command -v go >/dev/null 2>&1; then
  CAND="$(go env GOPATH 2>/dev/null)/bin/freeze"
  [ -x "$CAND" ] && FREEZE="$CAND"
fi

if [ -n "$FREEZE" ]; then
  "$FREEZE" --background "$BG" -o "$OUT" < "$ANSI"
  echo "rendered via freeze -> $OUT"
else
  HTML="${OUT%.png}.html"
  python3 "$HERE/ansi2html.py" "$ANSI" "$BG" "$HTML" >/dev/null
  CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  if [ ! -x "$CHROME" ]; then
    echo "ERROR: freeze not found and Chrome not at expected path." >&2
    echo "Install freeze (see SKILL.md) or adjust the Chrome path." >&2
    exit 1
  fi
  "$CHROME" --headless --disable-gpu --no-sandbox --hide-scrollbars \
    --window-size=1400,900 --screenshot="$OUT" "file://$HTML" 2>/dev/null
  echo "rendered via Chrome fallback -> $OUT (tune --window-size in this script if clipped)"
fi