Workflow & Core Tools · daymade/claude-code-skills

terminal-screenshot

Name: terminal-screenshot
Author: daymade/claude-code-skills

Render a terminal CLI program's colored output to a PNG so Claude can actually SEE the real visual result — color contrast, alignment, background blocks, highlighting — instead of only reading plain text and raw ANSI escape codes. Use this whenever verifying or debugging how a CLI tool looks in the terminal: delta git diff colors, bat syntax highlighting, starship prompt, eza/ls colors, git diff, ripgrep matches, or any ANSI-colored output. ALWAYS use it right after changing any CLI color config (delta / bat / themes / lazygit pager) to visually confirm the result rather than guessing from hex values — reading a hex code is not the same as seeing the rendered contrast on the real terminal background. Trigger phrases: 看终端效果, 终端截图, 验证配色, 配色对比, 终端真实效果, terminal screenshot, render terminal output, ANSI to image, "does this color look right", "is the contrast enough", delta/bat color verification.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；GitHub API spdx MIT）Commit d5c4678cb5

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The two-step separation is the core trick: first dump the full-fidelity ANSI into a .ansi file within the real shell of the CLI under test, then render it to PNG separately—never let the renderer execute the command for you, because freeze's child pty triggers delta/lazygit environment degradation detection, silently dropping background blocks, line number columns, and header boxes.

daymade-claude-code/terminal-screenshot/SKILL.md

The single most important rule: **never let the renderer run the command for you.**

The SKILL provides a counterexample: '`freeze --execute "git diff | delta"` looks convenient but produces a *degraded* result'. The capture side provides per-tool recipes (delta/git/bat/eza/ls/rg + CLICOLOR_FORCE=1 / script -q /dev/null).

Two-tier fallback on the rendering side: render_ansi.sh prioritizes freeze (charmbracelet, faithful background blocks/line number boxes), falling back to python3 ansi2html.py (pure stdlib ANSI→HTML) + headless Chrome screenshot if unavailable.

daymade-claude-code/terminal-screenshot/scripts/render_ansi.sh

# 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.

freeze locates PATH and then checks go env GOPATH/bin; the Chrome fallback path hardcodes macOS /Applications/Google Chrome.app, explicitly failing and exiting on non-macOS systems without freeze.

ansi2html.py only handles the SGR subset emitted by real CLIs: 24-bit truecolor (38;2;r;g;b / 48;2;r;g;b), 256 colors (38;5;n + xterm palette mapping), bold, and reset (0/39/49); crucially preserving background color blocks (delta addition/deletion highlights), with all text passed through html.escape to prevent injection.

daymade-claude-code/terminal-screenshot/scripts/ansi2html.py

Background color blocks (48;...) are preserved faithfully — that is the whole point, since tools like delta encode add/remove as background blocks.

In the render loop, `esc = H.escape(p)` precedes span wrapping—any HTML inside the ANSI text is escaped first, leaving no script injection surface in the generated page; xterm256 mapping has an independent implementation (base 16 + 232 grayscale + 6×6×6 cube).

The background color must match the real terminal; otherwise, dark themes on a white background will lead to misjudged contrast; the SKILL provides macOS Ghostty background retrieval commands and common defaults (#282c34/#1d1f21).

daymade-claude-code/terminal-screenshot/SKILL.md

**Background color must match the real terminal**, or a dark theme verified on a white page looks wrong.

The third parameter bg_hex of render_ansi.sh defaults to #282c34; 'Pass it as `#282c34`.'

TUI programs (lazygit/htop/top) are explicitly out of scope: they paint full screens using cursor positioning rather than linear ANSI streams, making capture with this method impossible; validating their colors requires isolating the underlying layers (e.g., lazygit diff via delta config).

daymade-claude-code/terminal-screenshot/SKILL.md

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

This is a capability boundary declaration rather than a defect: it instructs the agent when to switch to screencapture/computer-use workflows instead of forcing this approach.

Rendered results are read back by the agent using Read/image tools for visual inspection—replacing 'hex guessing' with 'evaluating real rendered contrast, alignment, and background blocks'.

daymade-claude-code/terminal-screenshot/SKILL.md

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

SKILL positioning: 'ALWAYS use it right after changing any CLI color config (delta / bat / themes / lazygit pager) to visually confirm the result rather than guessing from hex values'.

2Core Capabilities

01Render any ANSI-colored CLI output to PNG (delta/git/bat/eza/ls/rg, etc.) for visual color scheme inspection

02Per-tool recipe list for pre-render capture (including non-TTY forced coloring: --color=always / CLICOLOR_FORCE=1 / script -q /dev/null)

03freeze → Chrome two-tier fallback rendering (automatic degradation to a zero-dependency path when freeze is missing)

04stdlib ANSI→HTML converter faithfully preserving background color blocks, 24-bit truecolor, and 256 colors

05freeze installation guidance (avoiding the GUI cask of the same name: using the charmbracelet tap or go install + GOPROXY mirror / GOSUMDB=off)

3External Dependencies

Kind	Dependency / Endpoint
cli	freeze（charmbracelet/freeze，首选渲染器，可选）
cli	Google Chrome（无头模式，回退渲染路径；路径硬编码 macOS）
cli	python3（ansi2html.py 运行环境，纯 stdlib）
cli	go/brew（仅安装 freeze 时的可选项）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Local script or command execution: render_ansi.sh (bash, set -euo pipefail): executes freeze or python3 ansi2html.py + Chrome headless
网络端点: External network access declaration: None (scripts make zero network calls; freeze installation commands are user-initiated and can utilize go module mirrors)
本地工作目录: File I/O and artifact output: Writes output.png (and intermediate output.html in fallback paths) to user-specified paths; input .ansi is written by the user during the capture step to locations like /tmp

Audit Notes: Uses built-in stdlib/local scripts with no outbound network calls or credential access; the rendering chain relies on local freeze or local headless Chrome rendering local files. Caveats: the fallback path uses Chrome --no-sandbox (a security degradation flag, but applied strictly to html.escape-sanitized local HTML with no script injection vector); the Chrome path is hardcoded for macOS (explicitly errors out on non-macOS without freeze).

5Second-Pass Verification

[ok] 文本是否先转义再进 HTML（防注入） — ansi2html.py 'esc = H.escape(p)' 后拼入 span/裸文本；输出文档无其他用户可控拼接。
[ok] Chrome --no-sandbox 与降级面 — render_ansi.sh 回退路径含 --no-sandbox；渲染对象为本地生成、已转义的 HTML；freeze 存在时该路径不触发。
[ok] 无网络外发/凭证读取 — 两脚本无 curl/wget/http/url/env 密钥访问；go install 仅出现在 SKILL.md 安装指引（用户主动）。
[ok] SKILL 声称的每工具捕获配方 — 配方表为文档层指引（agent 在 shell 执行），脚本不含这些 CLI 调用，无隐藏依赖。
[ok] TUI 边界声明与实现一致 — SKILL 明确 TUI 光标定位无法线性捕获；脚本只处理线性 ANSI 流输入。
[unlocatable] freeze/Chrome 实际渲染保真度 — 依赖外部渲染器行为（背景块/行号盒/字体度量），本环境未实装 freeze/Chrome，未做端到端截图验证。

6Verdict & Scenarios

Resolves a real blind spot: allows agents to 'see' terminal colors instead of reading hex codes and raw escape sequences

Accurate design judgment with the two-step separation to avoid degradation (child pty detection is a real trap in delta/lazygit)

Fallback chains and boundary definitions ensure predictable operation or explicit failure when freeze is missing or on non-macOS

Injection surfaces are mitigated at the implementation layer (html.escape + parsing only 'm'-terminated SGR), leaving nothing to chance

Best for: Ideal for CLI color scheme/theme verification and debugging workflows: immediately rendering and confirming after modifying colors in delta/bat/starship/eza/ls/rg; suitable for agent visual QA needing 'what human eyes see in the terminal'; suitable for users with freeze installed or macOS + Chrome.

Not for: Not suitable for full-screen TUI (lazygit/htop) screenshots (use real terminal screenshots / computer-use instead); not suitable for non-macOS environments lacking freeze (fallback path is unavailable); not suitable for capturing interactive terminal sessions instead of rendering single command outputs.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload terminal-screenshot.tar.gz

sha256: f71128c440db3c5b…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.