lokkju/term-recorder

term-recorder 是做什麼的？

term-recorder 在固定尺寸的終端機中執行命令，按照步驟驅動它，並擷取螢幕上顯示的內容。當問題是「這在螢幕上看起來如何」，而閱讀程式碼無法回答時使用：例如對話框如何換行顯示長文字、Markdown 是否正確渲染、TUI 在 100 欄寬度下的表現、點擊位置落在何處。

它在其專屬的 tmux 伺服器 (tmux -L term-record-<pid>，使用產生的設定檔，無狀態列) 中執行命令，環境最小化，因此不會觸碰到使用者的 tmux 工作階段，命令也不會繼承此工作階段的變數。伺服器在執行結束後即被終止。

執行方式

呼叫 record 工具（term-recorder MCP 伺服器提供的；在 Claude Code 中為 mcp__plugin_term-recorder_term-recorder__record），並提供以下參數：

• command：程式及其引數組成的清單，例如 ["claude", "--model", "haiku"]。
• steps：內聯步驟，每行一個（見下方），或使用 steps_file 指定步驟檔案；兩者都會先執行檔案。步驟中的 ${EXAMPLES} 表示附帶的範例目錄。
• cwd：命令的起始工作目錄（預設為專案目錄）。內聯步驟中 include 和 paste 的路徑相對於此目錄。
• out：螢幕快照的輸出目錄（預設為新的暫存目錄）；此目錄會被建立。

每個 snap NAME 步驟會寫入 <out>/NAME.txt，並且結束時一定會擷取最終螢幕快照為 final。結果會包含每個快照的螢幕文字，以及快照儲存的路徑；閱讀這些文字檔即可得到答案。show: "final" 只回傳最終螢幕快照，show: "none" 則不回傳（但檔案仍會寫入）；snaps 工具可以列出先前執行的快照或依名稱讀取。若步驟失敗（等待超時、要點擊的文字不在螢幕上、命令已結束），結果會是錯誤訊息，指出失敗的步驟並顯示當時的螢幕內容。

check_steps 工具只解析步驟而不實際執行，是在進行會耗費實際 Claude Code 對話次數的執行前，一個低成本的安全檢查。

預設值：100x30 (size)、TERM screen-256color，以及僅從伺服器環境繼承 HOME、PATH、USER、LOGNAME、SHELL、LANG、LC_ALL、LC_CTYPE 和 TMPDIR。可使用 env（物件）或 pass（名稱）來新增變數，並使用 vars 進行步驟替換。

不使用 MCP 伺服器

在沒有伺服器的代理程式中，可以直接在相同程式碼上執行 CLI。將步驟寫入暫存目錄中的檔案，然後作為獨立的命令執行，不要串連到其他命令：

"${CLAUDE_SKILL_DIR}/scripts/term-record" -C <工作目錄> -s <步驟檔案> -o <輸出目錄> -- <命令> [引數...]

${CLAUDE_SKILL_DIR} 是存放此 SKILL.md 的目錄。Claude Code 會自動填入它；如果代理程式保留此變數不變，請將該目錄的實際路徑放入。快照會同時輸出到 stdout 和 <輸出目錄>。結束狀態 1 表示步驟失敗，並將螢幕內容輸出到 stderr；結束狀態 2 表示使用或設定問題。這些旗標與工具的引數對應：--size、--env NAME=VALUE、--pass NAME、--var NAME=VALUE、--cast、--gif、--agg-arg，以及 -s - 從標準輸入讀取步驟。

步驟

每行一個，使用 shell 引號，# 表示註解：

步驟	說明
wait REGEX [TIMEOUT]	等待螢幕符合正則表達式（Python re，支援多行；90 秒）
gone REGEX [TIMEOUT]	等待螢幕不再符合正則表達式
idle REGEX [QUIET] [TIMEOUT]	等待名為 REGEX 的忙碌標記消失持續 QUIET 秒（預設 3 秒；總超時 240 秒）
keys KEY...	傳送 tmux 按鍵名稱：Enter、Down、Escape、C-c
type TEXT [DELAY]	逐字輸入 TEXT，每個字元的間隔為 DELAY 秒（預設 0.03；設為 0 則一次全部傳送）
paste FILE	將 FILE 的內容以一次括號貼上的方式貼上，適合多行提示
click TEXT	左鍵點擊螢幕上第一個出現的 TEXT
sleep SECONDS	等待指定的秒數
snap NAME	擷取目前螢幕畫面為文字
resize COLSxROWS	在執行途中變更終端機尺寸；變更後拍攝快照以觀察佈局何處中斷
record on|off	開啟或關閉 cast 幀的錄製
include FILE	在此處執行 FILE 中的步驟
when REGEX STEP...	僅在螢幕目前符合正則表達式時才執行 STEP

include 和 paste 中的路徑相對於步驟檔案（對於內聯步驟則相對於 cwd）。

以 Claude Code 為目標

include ${EXAMPLES}/claude-start.steps 會啟動一個新的工作階段，跳過資料夾信任對話框，直接進入空白提示；請將其放在首位。${EXAMPLES}/ask-dialog.steps 是一個完整的範例，會開啟提問對話框並拍攝快照。

• 在暫存目錄中啟動它（cwd），使用較便宜的模型（--model haiku），除非模型本身很重要，並在 env 中加入 DISABLE_AUTOUPDATER=1，以免更新通知出現在畫面中。
• 若要測試某個外掛的開發版本，請加上 --plugin-dir <路徑>，並傳入 --settings <檔案> 來關閉已安裝的版本（"enabledPlugins": {"<名稱>@<市集>": false}）。
• 在 Claude 5 模型上，任務工具（TaskCreate 等）預設為關閉，無論是互動模式或 -p 模式，除非在 env 中設定了 CLAUDE_CODE_ENABLE_TODO_TOOLS=1。從 Claude Code 2.1.300 開始，--model haiku 指的是 Haiku 5.5，因此也包含此情況。即使是這樣，它們也是延遲工具：它們會出現在延遲工具清單中，並透過 ToolSearch 載入，而不是在初始工具清單中。
• 你的提示內容會顯示在螢幕上，因此請等待只有結果會顯示的文字（例如對話框的編號選項，如 '[0-9]\. Accept'），絕對不要等待提示本身中的任何單詞。
• Claude Code 的忙碌標記，供 idle 使用：'\([0-9]+m? ?[0-9]*s · |esc to interrupt'。
• 每次執行都是使用者帳號上的一次真實對話。請將步驟限制在檢查所需的回合數內。

錄製

cast 會寫入一個 asciicast v2 格式的檔案，而 gif 會透過 agg 將其渲染為 GIF（agg_args 可取代其引數）；結果會提供兩者的路徑。當螢幕內容變更時才會擷取幀；在 idle 等待期間，cast 的時鐘會以八倍慢速運行（busy_timescale），因此一分鐘的思考時間在播放時只需幾秒鐘。