termrec

ターミナル操作をイベントとして記録し、ブラウザ上で再生できる CLI ツールです。

画面録画の代わりに構造化 JSON データとして保存するため、軽量・編集可能・再利用しやすいのが特徴です。

---

特徴

• 記録: PTY 経由でターミナル操作をリアルタイムに記録
• 再生: ローカル HTTP サーバーを起動し、ブラウザ上でターミナル風に再生
• 編集: 不要な部分のトリミング、機密情報の置換、速度調整、注釈追加
• 注釈表示: 再生中に任意のタイミングでコメントをオーバーレイ表示

---

インストール

# リポジトリをクローン
git clone <repo-url>
cd termrec

# 依存パッケージをインストール・ビルド
pnpm install
pnpm build

ビルド後、packages/cli/dist/index.js が生成されます。グローバルに使う場合:

npm install -g .  # または packages/cli ディレクトリで

---

使い方

記録する

termrec record -o demo.termrec.json
termrec record --shell /bin/zsh --cols 120 --rows 32 -o demo.termrec.json
termrec record --title "AI デモ" --mask-home -o demo.termrec.json

オプション	説明
-o, --output <path>	出力ファイルパス
--shell <path>	起動するシェル（デフォルト: $SHELL）
--cols <number>	初期列数
--rows <number>	初期行数
--cwd <path>	初期作業ディレクトリ
--env <key=value>	追加環境変数（複数指定可）
--title <string>	セッションタイトル
--no-input-log	入力イベントを記録しない
--mask-home	ホームディレクトリを ~ に置換して保存

exit または Ctrl+D で記録終了、JSON ファイルに保存されます。

---

ブラウザで再生する

termrec play demo.termrec.json --open
termrec play demo.termrec.json --port 4312

ローカル HTTP サーバーが起動し、xterm.js ベースのプレイヤーがブラウザで開きます。
URL に ?speed=2 のようなクエリパラメータで初期再生速度を指定できます。

オプション	説明
--port <number>	ポート番号（デフォルト: 4312）
--host <string>	バインドホスト（デフォルト: 127.0.0.1）
--open	起動後にブラウザを自動で開く
--title <string>	表示タイトルを上書き

プレイヤーでは再生・一時停止・再開・速度変更（0.5x〜10x）が可能です。

---

記録ファイルの情報を確認する

termrec inspect demo.termrec.json

バージョン、記録日時、イベント数、総再生時間、画面サイズなどが表示されます。

---

編集する

# 3秒〜28秒の区間だけ切り出す
termrec edit demo.termrec.json -o output.termrec.json --from 3s --to 28s

# 機密文字列を置換する
termrec edit demo.termrec.json -o output.termrec.json --redact "/Users/yourname"="~"

# 再生速度（イベント間隔）を調整する
termrec edit demo.termrec.json -o output.termrec.json --speed 1.5

# 注釈を追加する
termrec edit demo.termrec.json -o output.termrec.json --annotate 12.5s="ここで AI がコード生成"

# 長い無音区間を最大5秒に抑える
termrec edit demo.termrec.json -o output.termrec.json --max-gap 5s

# 複数オプションを組み合わせる
termrec edit demo.termrec.json -o output.termrec.json --from 3s --to 60s --redact "secret"="***" --speed 1.2

オプション	説明
-o, --output <path>	出力ファイルパス
--from <time>	切り出し開始時刻（例: 3s, 1m30s, 1200ms）
--to <time>	切り出し終了時刻
--redact "<from>"="<to>"	文字列置換（複数指定可）
--speed <number>	イベント間隔の倍率（1.5 なら 1.5 倍速）
--annotate <time>="<text>"	指定時刻に注釈を挿入
--max-gap <time>	イベント間の無音区間の上限
--remove-input	入力イベントを除去

---

データフォーマット

記録ファイルは .termrec.json 拡張子のテキスト JSON です。

{
  "meta": {
    "version": 1,
    "title": "Claude Code デモ",
    "recordedAt": "2026-04-15T07:00:00+09:00",
    "shell": "/bin/zsh",
    "cols": 120,
    "rows": 32,
    "durationMs": 18234
  },
  "events": [
    { "t": 0,   "type": "resize", "cols": 120, "rows": 32 },
    { "t": 120, "type": "input",  "data": "ls\r" },
    { "t": 190, "type": "output", "data": "file1.txt\r\n" }
  ]
}

t はセッション開始からの相対ミリ秒です。

---

開発

# 依存インストール
pnpm install

# 全パッケージをビルド
pnpm build

# CLI のみビルド
pnpm build:cli

# プレイヤーの開発サーバー起動
pnpm dev:player

# テスト実行
pnpm test

パッケージ構成

termrec/
  packages/
    cli/      # Node.js CLI (record / play / inspect / edit)
    player/   # ブラウザプレイヤー (Vite + xterm.js)
  shared/     # 共通型定義・スキーマ (Zod)

---

動作環境

• Node.js 20+
• macOS（メインサポート）
• pnpm

---

ライセンス

MIT