關於這個 mod

本專案以 Claude Code 2.1.289 測試（0.1.2 以前使用 2.1.288）。已實際檢查 Markdown 排版、Ghostty 圖片像素（本機、herdr 0.9.3 內，以及 Air 透過 SSH 連線時）、連續影片影格、播放控制、送出前的貼圖預覽列，還有點擊回覆中的圖片路徑來開啟預覽。mosh 只會同步文字畫面，無法顯示圖片像素；Air 傳送剪貼簿到遠端，以及其他 Claude Code 版本，尚未完成驗證。 詳情請看相容性與驗證紀錄。

執行需求與試用

要使用本 Mod，需要能使用 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 市集，不需要私人 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 → 舊外掛 → Configure 記下已保存的 roots 與 autoPreview。接著卸載舊外掛，避免同名 Mod 同時被載入；卸載只會移除舊外掛保存的 options，不會影響其他外掛或市集：

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

然後安裝 tui-preview-mod@andrew54068，並從 Configure 重新套用剛才記下的設定；尤其是曾設成 false 的 autoPreview，否則它會回到預設 true。andrew54068 是 marketplace 名稱；tui-preview-mod 是 plugin 名稱；這個版本是 0.1.3。舊的 preview-mods 來源可以保留；切換來源不是用來繞過 Mod 開關的方式。

從 GitHub 安裝只會改變取得外掛的管道，不能保證 /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 工作階段，不會安裝到全域。進入後用 /plugin 確認 tui-preview-mod 是否已載入。組織政策或 rollout 狀態仍可能擋住 Mods；看到拒絕訊息不能算成功，也不要繞過政策。官方 Mods 說明

Plugin manifest 位於 tui-preview-mod/.claude-plugin/；marketplace manifest 位於 repository 根目錄的 .claude-plugin/。請分別指定檔案；只驗證 repository 目錄會選到 marketplace，漏掉 Mod 的 hooks／calls。原本的市集已有 metadata warnings，不能把它們和新外掛的 strict validation 混在一起。

使用方式

| 命令 | 效果 | | --- | --- | | /preview notes.md | 用原生 Markdown 分頁顯示 | | /preview images/photo with spaces.jpg | 顯示圖片；路徑中的空白會保留 | | /preview "videos/demo clip.mp4" | 以真正連續的影格播放影片，不播放聲音 | | 單擊回覆中的 content/a.png | 開啟同一個預覽 pane；需要全螢幕介面，詳見下文 | | /preview pasted | 開啟目前工作階段最近完成的貼圖預覽 | | /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 回覆裡的圖片或影片路徑會繪製成連結，單擊就能開啟預覽 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 更新一次；最多顯示兩張縮圖，其餘圖片要透過圖片按鈕明確載入。Read inline 與 composer 共用兩個自動解碼名額；前景 pane 是另外的明確操作。Mod 不會改寫輸入、不會送出 prompt，也不會改變 Read 傳給模型的內容。貼圖若尚未完成、讀取失敗，或自動預覽已關閉，/preview pasted 可能沒有可用快照；可用圖片按鈕重試。實作

格式與上限

| 項目 | 上限／行為 | | --- | --- | | Markdown：.md、.markdown | UTF-8，2 MiB；每頁最多 9000 字元單位，並移除終端控制字元 | | 圖片：PNG、JPEG、WebP、GIF | 來源 32 MiB；GIF 只取第一幀 | | 影片：MP4、MOV、WebM、MKV | 來源 2 GiB；能否解碼仍取決於已安裝的 ffmpeg | | 所有圖片／影片輸出 | PNG，最大 640×360，每幀最多 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 開關，而會沿用其他程序寫入 ~/.claude.json 的舊值；如果舊值是關閉，/preview 就不會出現 | 該工作階段的實驗功能都會改用內建預設（例如不啟用 Artifact 工具），也不會送出遙測 | | CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1 | herdr 回報的終端名稱是 libghostty，Claude Code 不認得它，因此停用圖片 | 終端不支援 Kitty 圖片時會畫出空白 | | FORCE_HYPERLINK=1 | 讓回覆中的路徑變成可點選連結 | 所有連結都改用終端超連結輸出 |

herdr 需要 0.9.3 以上；0.8.x 即使設為 kitty_graphics = true，直接送出的 Kitty 圖片仍會是空白。直接在 Ghostty 執行時，只有使用自訂 API 才需要第一項。

若不想每次都加 --settings，可把第一項放到 ~/.claude/settings.json 的 env；後兩項只在 herdr 內 export（herdr 的 pane 會有 HERDR_ENV）：

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

使用 cc-switch 這類會重寫 settings.json 的工具時，env 與 enabledPlugins 也要寫進它保存的設定，否則切換供應商後會消失。

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 已能繪出圖片像素。client 的剪貼簿不會因 SSH 自動變成 server 的剪貼簿：必須先讓圖片真正進入遠端 Claude composer，才會有可預覽的附件。

mosh 只同步文字畫面，不會轉送 Kitty 圖片協定，所以透過 mosh 看不到像素；pane、按鍵和點選仍可使用。Air 需要看到像素時，請改用 SSH。

更新與移除

在 shell 更新 GitHub catalog 與外掛，接著重新啟動 Claude 套用更新：

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

互動式 /plugin 沒有 update 子命令；也可以從 Installed 頁面的 Update now 更新，但不要使用 /plugin update。

只移除外掛並保留 marketplace：/plugin uninstall tui-preview-mod@andrew54068。不要為了移除此 Mod 而刪除整個 andrew54068 市集，那會影響其他外掛。 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 與解碼限制。
• 裝置安全檢查：發布前的六項唯讀檢查與兩項剩餘風險。
• 相容性、驗證紀錄：實測、自動測試與未驗證部分的界線。

MIT License，請見 LICENSE。