lokkju/term-recorder

term-recorder は何をしますか？

term-recorder は、固定サイズのターミナルでコマンドを実行し、ステップに従って操作し、表示内容をキャプチャします。「これが画面上でどのように見えるか」という、コードを読んでも答えが得られない質問（ダイアログが長いテキストをどのように折り返すか、マークダウンがレンダリングされるかどうか、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: ステップを1行につき1つずつインラインで指定するか（以下を参照）、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 <workdir> -s <steps> -o <outdir> -- <command> [args...]

${CLAUDE_SKILL_DIR} はこの SKILL.md が置かれているディレクトリです。Claude Code はこれを自動的に解決します。そのまま記述されたままのエージェントでは、そのディレクトリのパスを実際のパスに置き換えてください。 スナップは <outdir> に出力されるだけでなく、標準出力にも表示されます。 終了ステータス1はステップの失敗を意味し、その場合の画面は標準エラー出力に出力されます。ステータス2は使用方法またはセットアップの問題を示します。 フラグはツールの引数に対応しています: --size、--env NAME=VALUE、--pass NAME、--var NAME=VALUE、--cast、--gif、--agg-arg。-s - を指定すると、標準入力からステップを読み取ります。

ステップ

1行につき1つのステップ、シェル引用符、# はコメントです。

ステップ	説明
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秒）ごとに1文字ずつ入力します（0を指定すると即座に送信）
paste FILE	FILE を1つの括弧付きペーストとして貼り付けます。複数行のプロンプトに適しています
click TEXT	画面内で最初に見つかったTEXTの位置を左クリックします
sleep SECONDS	指定した秒数待機します
snap NAME	現在の画面をテキストとしてキャプチャします
resize COLSxROWS	実行中にターミナルのサイズを変更します。レイアウトが崩れる場所を確認するには、変更後にスナップを取得してください
record on|off	キャストフレームの記録をオンまたはオフにします
include FILE	その場所で FILE のステップを実行します
when REGEX STEP...	現在の画面が REGEX に一致する場合のみ STEP を実行します

include と paste のパスは、ステップファイルからの相対パスです（インラインステップの場合は cwd からの相対パス）。

Claude Code を対象とする場合

include ${EXAMPLES}/claude-start.steps を使用すると、フォルダ信頼ダイアログを通過して空のプロンプトが表示された新しいセッションを開始できます。これを最初に配置してください。 ${EXAMPLES}/ask-dialog.steps は、質問ダイアログを開いてスナップを取得する完全なサンプルです。

• スクラッチディレクトリ（cwd）で起動し、モデルが重要でない限り安価なモデル（--model haiku）を使用し、env に DISABLE_AUTOUPDATER=1 を指定して更新通知が画面に表示されないようにします。
• チェックアウトからプラグインを試すには、--plugin-dir <path> を追加し、--settings <file> を渡してインストール済みのコピーを無効にします（"enabledPlugins": {"<name>@<marketplace>": false}）。
• タスクツール（TaskCreate など）は、Claude 5 モデルでは、-p オプションを使用するインタラクティブモードであっても、env に CLAUDE_CODE_ENABLE_TODO_TOOLS=1 が設定されていない限りオフになっています。Claude Code 2.1.300 以降では、--model haiku は Haiku 5.5 を意味するため、Haiku もこれに含まれます。それでもこれらは遅延ツールです。初期ツールリストには表示されず、遅延ツールリストに表示され、ToolSearch を通じて読み込まれます。
• プロンプトは画面にエコーバックされるため、プロンプト自体の単語ではなく、結果のみに表示されるテキスト（ダイアログの番号付きオプション、例：'[0-9]\. Accept'）を待機するようにしてください。
• ビジーマーカー（idle 用）: '\([0-9]+m? ?[0-9]*s · |esc to interrupt'
• 各実行は、ユーザーのアカウント上の実際の会話となります。チェックに必要なターン数に抑えてください。

録画

cast は asciicast v2 ファイルを書き出し、gif は agg を使用してレンダリングします（agg_args で引数を置き換え可能）。結果は両方のパスを返します。 フレームは画面が変化したときにキャプチャされます。idle 待機中は、キャストの時計は8倍遅く動作するため（busy_timescale）、1分間の思考が数秒で再生されます。