About this mod

Claude Code 2.1.289 でテスト済みです（0.1.2 より前は 2.1.288）。Markdown のレイアウト、Ghostty の画像ピクセル（ローカル、herdr 0.9.3 内、Air から SSH 経由）、連続した動画フレーム、再生操作、送信前の貼り付け画像プレビュー、返信内の画像パスをクリックしてプレビューを開く動作を実測しました。mosh が同期するのはテキスト画面だけで、画像ピクセルは表示できません。Air からリモートへのクリップボード転送と、その他の Claude Code バージョンは未検証です。 詳細は互換性と検証記録を参照してください。

実行要件と試用

Mods を利用できる Claude Code、対話型ターミナル、そして Claude を実行するホストにインストールされた Node.js 20+、ffmpeg、ffprobe が必要です。Node は Claude プロセスの PATH に入っていなければなりません。メディアツールは /opt/homebrew/bin、/usr/local/bin、/usr/bin の順に探します。テスト環境は Node 26.8.1、ffmpeg／ffprobe 9.0.2 でした。すべての Node／codec バージョンを検証したわけではありません。

Yarn、node_modules、MCP server、ブラウザ、HTTP port は不要です。まず権限とデータ境界を読み、取得済みで信頼できるプロジェクトディレクトリから読み込んでください。

GitHub からインストール（推奨）

コードは andrew54068/claude-plugins の tui-preview-mod/ に公開されており、既存の andrew54068 marketplace を使うため、private repo へのアクセス権は要りません。インストールと Node／ffmpeg／ffprobe の準備は Claude を実行するホストで行う必要があります。 Air から SSH で Pro の Claude を使う場合、これらのツールが必要なのは Pro です。公式 marketplace 説明

Claude で次の順に実行します。

/plugin marketplace add andrew54068/claude-plugins
/plugin install tui-preview-mod@andrew54068
/reload-plugins
/preview README.md

andrew54068 が登録済みなら、ソースを再度追加する必要はありません。先に shell で claude plugin marketplace update andrew54068 を実行してからインストールしてください。

以前 tui-preview-mod@preview-mods をインストールした場合は、まず /plugin の Installed → 旧 plugin → Configure で保存済みの roots と autoPreview を控えます。その後、同名の Mod が同時に読み込まれないよう旧 plugin をアンインストールします。アンインストールで旧 plugin が保存した options は消えますが、他の plugin や marketplace には影響しません。

/plugin uninstall tui-preview-mod@preview-mods

次に tui-preview-mod@andrew54068 をインストールし、Configure で控えた設定を適用し直します。特に autoPreview を false にしていた場合は必ず戻してください。そうしないと既定値の true に戻ります。andrew54068 は marketplace 名、tui-preview-mod は plugin 名で、この版は 0.1.3 です。古い preview-mods ソースは残して構いません。ソースの切り替えは Mod のスイッチを回避する方法ではありません。

GitHub からのインストールで変わるのは plugin の取得方法だけで、/preview が必ず使えるようになるわけではありません。 まだコマンドがない場合は /plugin で mods active を確認し、shell で claude plugin test を実行して読み込み制限を調べてください。組織のポリシーや Anthropic の Mod スイッチによって拒否されることがあります。公式のトラブルシューティング

インストールしないローカル開発試用

claude --version
node --version
ffmpeg -version
ffprobe -version
claude plugin validate --strict /absolute/path/to/claude-plugins/tui-preview-mod/.claude-plugin/plugin.json
claude plugin validate /absolute/path/to/claude-plugins/.claude-plugin/marketplace.json
claude --plugin-dir /absolute/path/to/claude-plugins/tui-preview-mod

この読み込みはその Claude session にだけ適用され、全体にはインストールされません。起動後に /plugin で tui-preview-mod が読み込まれたか確認します。組織のポリシーや rollout の状態によって Mods がブロックされる場合もあります。拒否メッセージを成功扱いにしたり、ポリシーを回避したりしないでください。公式 Mods 説明

plugin manifest は tui-preview-mod/.claude-plugin/ に、marketplace manifest は repository ルートの .claude-plugin/ にあります。ファイルを別々に指定してください。repository ディレクトリだけを検証すると marketplace が選ばれ、Mod の hooks／calls が抜けます。元の marketplace には既存の metadata warnings があるため、新しい plugin の strict validation と混同しないでください。

使い方

| コマンド | 効果 | | --- | --- | | /preview notes.md | ネイティブ Markdown のページとして表示 | | /preview images/photo with spaces.jpg | 画像を表示。パス内の空白は保持 | | /preview "videos/demo clip.mp4" | 音声なしで実際の連続フレームとして動画を再生 | | 返信内の content/a.png をシングルクリック | 同じ preview pane を開く。全画面インターフェースが必要です | | /preview pasted | 現在の session で直近に完了した貼り付け画像のプレビューを開く | | /preview close | pane を閉じ、デコーダープロセスを停止 | | /preview on、/preview off | 今回の読み込みで自動貼り付け／Read 画像プレビューを切り替え | | /preview | 操作説明を表示 |

パスは既定では現在の session.root() に制限されます。追加ディレクトリは /plugin の tui-preview-mod 設定に絶対パスで明示的に追加してください。使用できるのは最大 32 個です。autoPreview は再読み込み時の既定値を制御し、on/off は設定を保存しません。off にしても明示的なパスのプレビューは妨げません。

動画は p で再生／一時停止、h で 5 秒進む、l で 5 秒戻る、r で再生し直す、x または Esc で閉じます。Markdown は h/l またはボタンでページを移動します。まず pane にキーボードフォーカスを渡してください。ネイティブの Ctrl-X Tab でフォーカスを切り替えられます。

返信内のパスをクリック

全画面インターフェース（CLAUDE_CODE_NO_FLICKER=1 または /tui fullscreen）では、Claude の返信に含まれる画像・動画パスがリンクとして描画され、シングルクリックで preview pane が開きます。相対パスは session.root() を基準に解決し、絶対パスは許可された roots 内に必要があります。

• Cmd+click はターミナルが処理します：Ghostty は macOS でファイルを開くため、Mod はこのクリックを受け取りません。シングルクリックを使ってください。Ctrl／Alt+click は Claude Code 本来の開き方のままです。
• メディアパスに言及した返信だけを再描画し、それ以外はネイティブ描画のままです。保存済みメッセージやモデル入力は書き換えません。再描画後に選択できないリンク（vscode://、mailto:、Email など）が返信に含まれる場合は、返信全体をネイティブ描画します。
• クリック前にファイルは読みません。クリック後は /preview <path> と同じディレクトリ、サイズ、形式の検査を行います。
• Claude Code が選択可能なリンクを描画できるターミナルでだけ返信を再描画します。Ghostty、iTerm2、WezTerm、kitty、Alacritty、Warp、VS Code 1.72+、tmux 3.4+ などが対象で、判定方法は 2.1.289 に合わせています。Terminal.app と herdr（TERM_PROGRAM=herdr）は対象外で、返信はネイティブ描画です。herdr で FORCE_HYPERLINK=1 を設定すれば選択可能なパスになります。詳しくはカスタム API と herdrを参照してください。
• 返信を再描画したくない場合は、/plugin の設定で clickablePaths を false にします。

ネイティブの貼り付け画像が現在の composer に入ると、プレビュー列は約 500ms ごとに更新されます。サムネイルは最大 2 枚で、残りは画像ボタンから明示的に読み込みます。Read inline と composer は 2 つの自動デコード枠を共有し、前面の pane は別の明示操作です。Mod は入力を書き換えず、prompt を送信せず、Read がモデルに渡す内容も変えません。貼り付けが未完了、読み込み失敗、自動プレビュー停止のいずれかなら、/preview pasted に使えるスナップショットがない場合があります。画像ボタンから再試行できます。実装

形式と上限

| 項目 | 上限／動作 | | --- | --- | | Markdown：.md、.markdown | UTF-8、2 MiB。1 ページ最大 9000 文字単位、ターミナル制御文字を除去 | | 画像：PNG、JPEG、WebP、GIF | 入力 32 MiB。GIF は最初のフレームだけ | | 動画：MP4、MOV、WebM、MKV | 入力 2 GiB。デコード可否はインストール済み ffmpeg に依存 | | すべての画像／動画出力 | PNG、最大 640×360、1 フレーム最大 2 MiB | | 動画再生 | 8 fps、音声なし。ソースの先頭 600 秒だけをプレビューし、シークもこの範囲に制限 |

URL、デバイス、FIFO、範囲外のファイル、ファイル symlink はサポートしません。PNG bytes はネイティブの Image／ui.blit に渡します。ターミナルがピクセルを描けない場合は、ネイティブの代替テキストを表示できます。独立したプレーヤーではなく、リモート Claude のない SSH ファイルブラウザでもありません。helper

カスタム API と herdr

settings でカスタム ANTHROPIC_BASE_URL／ANTHROPIC_AUTH_TOKEN を使うか、herdr 内で Claude を実行するときは次のコマンドで起動します。

claude --settings '{"env":{"DISABLE_TELEMETRY":"1","CLAUDE_CODE_FORCE_TERMINAL_IMAGES":"1","FORCE_HYPERLINK":"1"}}'

| 設定 | 理由 | 代償 | | --- | --- | --- | | DISABLE_TELEMETRY=1 | カスタム API では、Claude Code はこのプロセスの Mods スイッチを flag service から取得せず、別のプロセスが ~/.claude.json に書いた古い値を使います。古い値がオフなら /preview は表示されません | その session の実験機能は組み込み既定値に切り替わり（たとえば Artifact ツールを有効にしない）、テレメトリーも送信しません | | CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 | herdr が返すターミナル名は libghostty で、Claude Code が認識できず画像を無効にします | ターミナルが Kitty 画像に対応しないと空白が描画されます | | FORCE_HYPERLINK=1 | 返信内のパスを選択可能なリンクにします | すべてのリンクがターミナルのハイパーリンク出力になります |

herdr は 0.9.3 以上が必要です。kitty_graphics = true を設定しても、0.8.x では直接送信した Kitty 画像が空白になります。Ghostty で直接実行する場合、最初の設定が必要なのはカスタム API のときだけです。

毎回 --settings を付けたくなければ、最初の設定を ~/.claude/settings.json の env に入れ、後の 2 つは herdr 内でだけ export します（herdr の pane には HERDR_ENV があります）。

if [[ -n $HERDR_ENV ]]; then
  export CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 FORCE_HYPERLINK=1
fi

settings.json を書き換える cc-switch のようなツールを使う場合、保存される設定にも env と enabledPlugins を書いてください。そうしないと provider を切り替えた後に消えます。

SSH

ファイルがあるリモートホストで Claude Code + この Mod + Node／ffmpeg／ffprobe を実行し、client のターミナルから表示します。既存の信頼できる SSH 接続を使えばよく、Mod のために port を開く必要はありません。

ssh your-trusted-host
claude --plugin-dir /absolute/path/on/remote/claude-plugins/tui-preview-mod

Air から SSH で Pro の herdr に接続し、上のコマンドで起動すると、Air の Ghostty で画像ピクセルを描画できました。SSH だからといって client のクリップボードが server のクリップボードになるわけではありません。プレビューするには、画像が実際にリモート Claude の composer に入っている必要があります。

mosh はテキスト画面だけを同期し、Kitty 画像プロトコルを転送しないため、mosh 経由ではピクセルを見られません。pane、キー、クリックは使えます。Air からピクセルを見る必要があるときは SSH を使ってください。

更新と削除

shell で GitHub catalog と plugin を更新し、Claude を再起動して適用します。

claude plugin marketplace update andrew54068
claude plugin update tui-preview-mod@andrew54068

対話型 /plugin には update サブコマンドがありません。Installed ページの Update now からも更新できますが、/plugin update は使わないでください。

marketplace を残して plugin だけ削除します：/plugin uninstall tui-preview-mod@andrew54068。この Mod を削除するために andrew54068 marketplace 全体を削除しないでください。他の plugin にも影響します。 shell での同等コマンドは先頭の / を外し、plugin の前に claude を付けます。既定以外の scope でインストールした場合は、削除時も同じ --scope を指定します。

--plugin-dir だけで試用している場合は、次回その引数を付けなければ構いません。公式 marketplace 説明

開発とドキュメント

開発には Yarn Classic を使います。yarn run check が検証するのは Node/helper core だけです。ネイティブ Mod には claude plugin test . と、runtime で型を生成した後の Mod typecheck も必要です。完全なコマンドは CONTRIBUTING を参照してください。

• 繁体字中国語の研究レポート：Mod を採用した理由、SSH と権限のトレードオフ。
• SECURITY：一般的な Mods の権限、このプロジェクトの footprint、デコード制限。
• デバイス安全性チェック：リリース前の 6 つの読み取り専用チェックと、残る 2 つのリスク。
• 互換性、検証記録：実測、自動テスト、未検証の境界。

MIT License。詳しくは LICENSE を参照してください。