1仕組みと動作原理
2ステップの分離がコアとなる手法です：まずテスト対象CLIの実シェル上で完全忠実なANSIを.ansiファイルに出力し、その後単独でPNGにレンダリングします。レンダラーにコマンドを実行させてはなりません。freezeの子ptyにより、deltaやlazygitが環境のデグレードを検知し、背景ブロック、行番号列、ヘッダー枠を暗黙的に破棄してしまうためです。
daymade-claude-code/terminal-screenshot/SKILL.md
The single most important rule: **never let the renderer run the command for you.**
SKILLにおける反例の提示：'`freeze --execute "git diff | delta"` looks convenient but produces a *degraded* result'。キャプチャ側にはツールごとのレシピ（delta/git/bat/eza/ls/rg + CLICOLOR_FORCE=1 / script -q /dev/null）が用意されています。
レンダリング側の2段階フォールバック：render_ansi.shはfreeze（charmbracelet、背景ブロックや行番号ボックスを忠実に再現）を優先し、見つからない場合はpython3 ansi2html.py（純粋なstdlibによるANSI→HTML）+ ヘッドレスChromeによるスクリーンショットへフォールバックします。
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はPATHを確認した後にgo env GOPATH/binを探索します。ChromeのフォールバックパスはmacOSの/Applications/Google Chrome.appにハードコードされており、非macOSかつfreezeが存在しない場合は明確にエラー終了します。
ansi2html.pyは実際のCLIが出力するSGRサブセットのみを処理します：24ビットtruecolor（38;2;r;g;b / 48;2;r;g;b）、256色（38;5;n + xtermパレットマッピング）、bold、reset（0/39/49）。背景色ブロック（deltaの追加・削除背景色）を忠実に保持することが重要であり、テキストはインジェクションを防ぐためすべてhtml.escapeを通します。
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.
レンダリングループ内で`esc = H.escape(p)`を実行してからspanで囲みます。ANSIテキスト内のいかなるHTMLも事前にエスケープされるため、生成ページにスクリプトインジェクションの脆弱性はありません。xterm256マッピングには独自実装（基本16色 + 232グレースケール + 6×6×6キューブ）が含まれます。
背景色は実際のターミナルと一致させる必要があります。一致しない場合、白背景上のダークテーマでコントラストを誤判定します。SKILLにはmacOS Ghosttyの背景色取得コマンドと一般的なデフォルト値（#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.
render_ansi.shの第3引数bg_hexはデフォルトで#282c34です。'Pass it as `#282c34`.'
TUIプログラム（lazygit/htop/top）は明示的に対象外と定義されています：これらは線形なANSIストリームではなくカーソル位置指定を用いて全画面を描画するため、本手法でのキャプチャは不可能です。色の検証には基盤となるレイヤーを切り出す必要があります（例：lazygitのdiff表示にはdeltaの設定を使用）。
daymade-claude-code/terminal-screenshot/SKILL.md
## TUI programs (lazygit, htop, top) — out of scope
これは欠陥ではなく能力の境界宣言です。無理に適用することを防ぎ、screencaptureやcomputer-useのアプローチに切り替えるべきタイミングをエージェントに指示します。
レンダリング結果はエージェントがRead/画像ツールを用いて読み戻し、視覚的な判断を行います。「16進数による色推測」を「実際のレンダリング結果におけるコントラスト、配置、背景ブロックの確認」へと置き換えます。
daymade-claude-code/terminal-screenshot/SKILL.md
Then read the PNG with the Read tool and judge the colors.
SKILLの用途の位置付け：'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'。
2コア機能
01任意のANSIカラーCLI出力（delta/git/bat/eza/ls/rgなど）をPNGにレンダリングし、配色の視覚的判断を提供
02レンダリング前キャプチャ用のツール別レシピ集（非TTY強制カラー化：--color=always / CLICOLOR_FORCE=1 / script -q /dev/null を含む）
03freeze → Chromeの2段階フォールバックレンダリング（freeze不在時は依存関係なしのパスへ自動ダウングレード）
04背景色ブロック、24ビットtruecolor、256色を忠実に再現するstdlib ANSI→HTMLコンバーター
05freezeのインストールガイド（同名のGUI caskを避け、charmbracelet tapまたはgo install + GOPROXYミラー/GOSUMDB=offを使用）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | freeze（charmbracelet/freeze，首选渲染器，可选） |
| cli | Google Chrome（无头模式，回退渲染路径；路径硬编码 macOS） |
| cli | python3（ansi2html.py 运行环境，纯 stdlib） |
| cli | go/brew（仅安装 freeze 时的可选项） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: render_ansi.sh（bash、set -euo pipefail）：freezeまたはpython3 ansi2html.py + Chromeヘッドレスを実行
- 网络端点: 外部ネットワークアクセスの宣言: なし（スクリプト内でのネットワーク呼び出しはゼロ。freezeのインストールコマンドはユーザー主導の操作であり、go moduleミラー経由が可能）
- 本地工作目录: ファイルの読み書きと成果物の出力: ユーザー指定のパスにoutput.png（およびフォールバックパスの中間ファイルoutput.html）を出力。入力となる.ansiはキャプチャ工程でユーザー自身が/tmp等に保存
監査ノート： 標準ライブラリおよびローカルスクリプトを内包し、外部ネットワーク送信や認証情報の読み取りはありません。レンダリングパイプラインはローカルのfreezeまたはローカルChromeヘッドレスによるローカルファイル描画で完結しています。留意点：フォールバックパスではChromeの--no-sandbox（セキュリティレベル低下フラグですが、対象はhtml.escape処理済みのローカルHTMLでありスクリプトインジェクション経路は存在しません）を使用し、ChromeのパスはmacOS向けにハードコードされています（非macOSでfreezeがない場合は明示的にエラー終了します）。
5二重目の独立検証
- [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，未做端到端截图验证。
6結論
最適な用途： CLIの配色・テーマの検証およびデバッグワークフローに最適：delta/bat/starship/eza/ls/rgの色変更直後にレンダリングして確認する場合。「ターミナルで人間の目にどう見えるか」を必要とするエージェントのビジュアルQA。freezeを導入可能な環境、またはmacOS + Chromeのユーザー向け。
不向きな用途： フルスクリーンTUI（lazygit/htop）のキャプチャには不向き（実際のターミナル画面キャプチャ/computer-useを使用すべき）。freezeがなく、かつ非macOSの環境には不向き（フォールバックパスが利用不可）。単一出力のレンダリングではなく、インタラクティブなターミナルセッション全体のキャプチャを必要とするシーンには不向き。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload terminal-screenshot.tar.gz
sha256:
Option B · Copy Guide for Agentf71128c440db3c5b…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.