talkthru

talkthru

talkthru.dev · npm · @dr_edon · MIT

あらゆるアプリで使える自動フィードバックループです。 スマートフォンでアプリの画面を録画し、使いながら話します。録画をマシンに送ると、コーディングエージェントはあなたの発言をすべて、話したときに見ていた画面と紐づけて受け取ります。

you:    *tapping through checkout* "this button is too small, I keep missing it"
                                  "and this error doesn't say what went wrong"

agent:  sees both screens, finds both components, fixes them.

すべてマシン上で動作します。アカウントも、アップロードも、API キーも不要です。

Mac の画面収録（⌘⇧5）、AirDrop 経由で送った iPhone の録画、または Windows Game Bar に対応しています。音声付きの動画なら何でも使えます。監視対象のフォルダーを指定してください。

70 秒のデモ — インストール、録画、エージェントによる取り込み。

---

インストール

npx talkthru doctor --fix

ffmpeg、whisper.cpp、音声モデルをダウンロードします。それ以外に設定は不要です。

ウォッチャーを起動する

npx talkthru watch

起動したままにしてください。画面収録と同じ名前のファイルだけを処理するため、Downloads フォルダー内のほかのファイルが見られることはありません。

エージェントを接続する

talkthru は MCP サーバーなので、Cursor、Windsurf、Cline、Zed、Claude Desktop など、どの MCP クライアントでも使えます。クライアントの設定に追加してください。

{
  "mcpServers": {
    "talkthru": {
      "command": "npx",
      "args": ["talkthru-mcp"]
    }
  }
}

Claude Code では、同じ設定を 1 行で行えます。

claude mcp add --scope user talkthru -- npx talkthru-mcp

サーバーを読み込ませるため、設定後にクライアントを再起動してください。

Claude Code を使って構築し、テストしています。ほかの MCP クライアントでも動作するはずです。お使いのクライアントで動かない場合はお知らせください。

---

Mac をセットアップする

初回のみ。⌘⇧5 を押して、収録モード（◉のドットが付いたアイコン）を選び、オプションを開いて、保存先 → ダウンロードとマイクを設定します。設定はどちらも保持されます。

1 · 2. ⌘⇧5を押し、収録モードを選んで、オプションを開きます
3. 保存先 → ダウンロード — talkthru watchが確認するフォルダーです	4. マイクで使うマイクを選びます
5. 収録を押して、アプリを使いながら話します

マイクが選択されていないと、動画は無音になり、文字起こしもできません。初めて録画する前に確認してください。

---

スマートフォンをセットアップする

任意です。デスクトップではなく、スマートフォンのアプリを録画したい場合のみ設定してください。

初回のみ。コントロールセンター → ＋ → コントロールを追加 → 画面収録の順に選択します。次に、画面収録を長押しして、マイクをオンにします。

1. ＋をタップ	2. コントロールを追加	3. 画面収録を選択
4. ◉を長押し	5. マイクをオン	6. ◉をタップして話します

---

Web アプリを記録する

任意 — エージェントに、指し示していた要素そのものを渡すドロップインスクリプトです。画像だけを渡すのではありません。

<script src="/talkthru-dom.js"></script>

記録後、コンソールで talkthru.stop() を実行すると hierarchy.json がダウンロードされます。2つを一緒に処理します。

talkthru process ~/Downloads/screen-recording.mov --hierarchy ~/Downloads/hierarchy.json

スクリプトとキャプチャ内容： clients/web。

---

使い方

1. アプリを記録しながら、話してください
2. 動画をマシンに転送します（AirDrop が最も簡単です）
3. エージェントに「前回の talkthru セッションのフィードバックを確認して実装して」と頼みます

約20秒で準備できます。元の動画は ~/.talkthru/archive/ に保存されます。

アプリが音声を出す場合は、ミュートしてください。 アプリの音声もあなたの音声の横に文字起こしされ、whisper では区別できません。

---

出力

発話したときに表示されていた画面に紐づいた、あなたの言葉です。

## 00:34 · f11 — `frames/f11.jpg`
- [00:39] "this button is too small, I keep missing it"

## 00:52 · f13 — `frames/f13.jpg`
- [00:55] "and this error doesn't say what actually went wrong"

さらにフレームも含まれます。2分のセッションは約600トークンです。

---

要素のコンテキスト（任意）

UI 階層ファイルを talkthru に渡すと、エージェントはピクセルから対象のコンポーネントを推測する代わりに、要素の種類、ラベル、安定したテスト IDを取得できます。

talkthru process recording.mp4 --hierarchy hierarchy.json

## 00:34 · f11 — `frames/f11.jpg`
ui: button#checkout-submit "Place order" @24,680 342x48
- [00:39] "this button is too small, I keep missing it"

これはアプリが書き出すタイムスタンプ付きのサイドカーファイルです。ここでは生成されず、形式は iOS 固有の前提がないプレーンな JSON です。

{ "snapshots": [
  { "tMs": 1200, "nodes": [
    { "type": "button", "testId": "checkout-submit", "label": "Place order",
      "rect": [24, 680, 342, 48], "depth": 4 }
  ] }
] }

よくある別名（tag、id、text、bounds、elements、…）もそのまま受け付けるため、DOM クライアントは通常、自然な形式で出力できます。不正なファイルは記録を失敗させるのではなく、警告を出して無視されます。

完全な形式：docs/hierarchy.md — フィールド、別名、ランキング規則、クライアントの作成方法について説明しています。

---

ネットワークとコンソール（任意）

録画の隣に events.json を置くと、失敗したリクエストが、見ていたフレームの下に表示されます。

## 00:34 · f11 — `frames/f11.jpg`
ui: button#checkout-submit "Place order" @24,680 342x48
net: POST https://api.example.com/checkout 500 340ms
- [00:39] "I tapped place order and nothing happened"

{ "events": [
  { "tMs": 12400, "kind": "network", "method": "POST",
    "url": "https://api.example.com/checkout", "status": 500, "durationMs": 340 },
  { "tMs": 12450, "kind": "console", "level": "error", "text": "TypeError: ..." }
] }

ヘッダーも本文も記録しません — 認証トークンはヘッダーに含まれており、このツールの目的はデータをマシン上に保つことです。秘密情報に見えるクエリ値は、解析時に REDACTED に置き換えられます。送信した内容はすべて保存されますが、デフォルトでエージェントに渡されるのは失敗と error／warn のみです。2分間の XHR は、フレームとナレーションを合わせた量よりも長いテキストになるためです。

完全な形式：docs/events.md

---

Windows

Win+Alt+R（Game Bar）で Videos\Captures に録画されます。ここがウォッチャーのデフォルトの監視先です。このフォルダーにはほかに何も入っていないため、名前によるフィルターはありません。

winget install -e --id Gyan.FFmpeg
npx talkthru watch

whisper.cpp には winget パッケージがありません。ggml-org/whisper.cpp からビルドし、TALKTHRU_WHISPER にバイナリのパスを指定してください。

Windows 向けに作成し、ユニットテストも行っていますが、まだ Windows マシンでは実行していません — Windows マシンを持っていないためです。試した場合は、動作したかどうかにかかわらず、Issue を報告していただけると役立ちます。

---

コマンド

talkthru watch                  # watch ~/Downloads for screen recordings
talkthru watch ~/some-folder    # watch your own folder, any video
talkthru process video.mp4      # process one file
talkthru list                   # recent sessions
talkthru show latest            # print one
talkthru doctor                 # check the setup
talkthru compact                # reclaim disk: drops old originals, keeps every frame + transcript
talkthru prune                  # delete old sessions entirely

tt も使えます。

---

仕組み

ffmpeg が画面に実際に変化があった箇所のフレームを取り出します。whisper.cpp はローカルで音声を文字起こしし、文と文の間の実際の無音区間で分割するため、発話の一つひとつが、そのとき見ていた画面に紐づきます。MCP サーバーがそれをエージェントに渡します。

Node 20.11 以降が必要です。

---

理由

毎日、自分のアプリをスマートフォンでテストしていますが、スクリーンショットを撮って切り抜き、どの画面のことか説明しようとしているうちに、エディターに戻るまでの間にフィードバックを見失ってしまうことがよくありました。今は録画して話すだけで、Claude Code が内容を取り込んでくれます。同じ手間を省く助けになればと思い、共有します。