terminal-screenshot

ターミナルのスクリーンショット

ターミナルコマンドのカラー出力をPNG画像にレンダリングし、その画像を読み取って結果を視覚的に判断します。

これが必要な理由

コマンドの出力がツールの結果として届くと、Claude が目にするのはプレーンテキストと、\x1b[48;2;92;30;34m のような生のエスケープコードです。レンダリングされた色は見えません。そのため、「差分の追加／削除のコントラストは十分か？」や「このテーマは暗すぎないか？」といった質問に、正直に答えることができません。16 進数の値を読むだけでは推測にすぎません。このスキルでは、出力を画像に変換し、人が画面上で実際に見るものを基に判断できるようにします。

方法：キャプチャしてからレンダリング

手順は 2 つです。分けて行ってください。この分離が肝心です。

ステップ 1 — ANSI 出力を完全な状態でファイルにキャプチャする

ほとんどの CLI は、実際のターミナルに出力していない（パイプや子プロセスへの出力など）と判断すると、色を落とすか、簡略化します。フルカラーを強制し、.ansi ファイルに保存してください。正確なフラグはツールによって異なります。手順は以下を参照してください。

最も重要なルールは、レンダラーにコマンドを実行させないことです。 freeze --execute "git diff | delta" は便利そうに見えますが、劣化した結果になります。delta（および lazygit や、ターミナル機能を調べるあらゆるツール）は freeze の子 pty 内で実行され、環境が制限されていることを検出すると、背景のブロック、行番号の列、ヘッダーボックスを黙って省略します。まず通常のシェルでキャプチャし、その後でレンダリングしてください。

ステップ 2 — ANSI ファイルを PNG にレンダリングして読み取る

freeze を優先し、利用できない場合は標準ライブラリのレンダラーとヘッドレス Chrome にフォールバックする、同梱のラッパーを使用してください。

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

次に Read ツールで PNG を読み取り、色を判断してください。

背景色は実際のターミナルと一致させてください。 そうしないと、白いページで検証したダークテーマは実際と違って見えます。macOS で Ghostty を使用している場合：

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

#282c34 として渡してください。不明な場合、ダークターミナルの色は通常 #1d1f21～#282c34 付近です。

ツールごとのキャプチャ手順

折り返し位置が一致するよう、--width は実際のターミナルに近い値（約 100～120）にしてください。

ツール	キャプチャコマンド（フルカラーの ANSI 出力を保存）
delta（git diff）	git --no-pager diff | delta --dark --line-numbers --width=110 > /tmp/x.ansi
git diff（ネイティブ）	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
その他	CLICOLOR_FORCE=1 <cmd> > /tmp/x.ansi または <cmd> --color=always を使用するか、実際の pty でラップします：script -q /dev/null <cmd>

delta はファイルへの出力でも設定済みの色を常に出力するため、delta で注意すべき点はステップ 1 のルールのみです（freeze --execute 経由でレンダリングしないでください）。

完全な例：delta の色変更を検証する

# 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 プログラム（lazygit、htop、top）— 対象外

全画面 TUI は、線形の ANSI ストリームではなくカーソル位置指定で描画するため、この方法ではキャプチャできません。TUI の色を確認するには、基となる部分を個別に検証してください。たとえば lazygit の差分なら、上記のように git diff | delta をレンダリングします（lazygit は同じ delta 設定を呼び出します）。実際の TUI のスクリーンショットを撮る場合は、実際のターミナルで実行して画面をキャプチャしてください（スクリーンキャプチャ／コンピューター操作タスク）。このスキルは使用しないでください。

freeze のインストール（推奨レンダラー）

freeze は charmbracelet/freeze です。ANSI を、背景ブロックと美しいウィンドウ枠を忠実に再現しながら PNG／SVG／WebP にレンダリングします。

brew install freeze は実行しないでください。同じ名前の無関係な GUI アプリ（cask）がインストールされます。CLI は charmbracelet の tap、または 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"

チェックサムデータベース（sum.golang.org）にアクセスできず、go install が「verifying module ... 504」で停止する場合は、GOSUMDB=off が必要です。

freeze をインストールできない場合、ラッパーは自動的に同梱の scripts/ansi2html.py（標準ライブラリのみ）とヘッドレス Chrome にフォールバックします。Chrome のインストール以外に追加の依存関係はありません。フォールバックではウィンドウサイズが固定されるため、出力が切れる場合は render_ansi.sh の --window-size を大きくしてください。

同梱スクリプト

• scripts/render_ansi.sh — キャプチャした .ansi ファイルを PNG にレンダリングします（freeze を使用し、利用できない場合は Chrome にフォールバック）。エントリーポイントです。ステップ 1 の後に呼び出してください。
• scripts/ansi2html.py — フォールバックで使用する、標準ライブラリの ANSI→HTML コンバーターです。24 ビットトゥルーカラー、256 色、太字、リセットに対応し、背景色ブロック（単純なレンダラーでは欠落する部分）を保持します。

よくある落とし穴

• レンダラーにコマンドを実行させる（freeze --execute "delta …"）→ 出力の品質が低下します。まず通常のシェルでキャプチャし、その後ファイルをレンダリングしてください。
• 非 TTY では色が除去される → 強制的に有効にしてください（--color=always／CLICOLOR_FORCE=1／script -q /dev/null）。
• 背景色が正しくない → 白いページにダーク CLI テーマをレンダリングすると、コントラストの判断を誤ります。実際のターミナルの背景色を使用してください。
• ライト／ダークの不一致 → ターミナルがダークなら、CLI の色もダークバリアントである必要があります。ダークターミナルで light=true の設定を検証すると、色が反転して読みにくくなります（これはレンダラーの問題ではなく、それ自体が不具合です）。
• brew install freeze は誤ったツール（GUI cask）をインストールします。tap または go install を使用してください。