baguette

baguette — プログラムによる iOS シミュレーター制御

baguette は、Apple のプライベートな SimulatorHID（Xcode が内部で使用する経路）を通じて iOS シミュレーターを操作する macOS CLI です。入力操作では idb／AXe／simctl io より高速で信頼性があります。エージェントは CLI を操作します。画面を見たり、一緒に操作したりしたい人には、baguette serve と http://localhost:8421/simulators/<udid> を案内してください。

操作の流れ

ほとんどの作業は、デバイスを取得し、操作し、確認して、繰り返す流れです。

baguette list --json                                    # 1. a booted UDID
baguette boot --udid <UDID>                             #    (if none is running)
baguette describe-ui --udid <UDID> | jq .screen        # 2. its size in points
baguette tap --udid <UDID> --x 219 --y 478 --width 438 --height 954   # 3. act
baguette screenshot --udid <UDID> --output /tmp/frame.jpg             # 4. look

次に Read /tmp/frame.jpg を実行します。タップに対して {"ok":true} が返るのに何も起きない場合は、baguette heal --udid <UDID> を実行してください（Xcode 27 の Device Hub が入力サーフェスを引き継いでいます。references/devices.md を参照してください）。

座標はデバイスのポイント単位です（必ず確認してください）

すべての x／y／startX／endX／x1／cx … はデバイスのポイント単位で、同時に指定する width／height と同じ単位です。438×954 の画面の中心は x:219, y:478 です。0.5, 0.5（正規化座標）でも、1206, 2622（ピクセル）でもありません。デバイスごとに describe-ui の外側にある screen から width／height を取得し、回転または折りたたみの後はもう一度確認してください。フレームも同じ単位で返されるため、要素の中心座標をそのままタップに使えます。chrome layout は使わないでください。そこの screen はベゼル画像の座標であり、デバイスのポイント単位ではありません。

何をしますか？

作業に必要なリファレンスだけを読んでください。

目的	読むもの	コマンド
デバイスを起動し、サイズや向き、折りたたみ状態を設定する。入力がどこにも届かない問題を解決する	references/devices.md	list boot shutdown heal orientation hinge
ユーザーのように操作する：タッチ、ドラッグ、ボタンの押下、入力、貼り付け	references/interact.md	tap double-tap swipe pinch pan input press type key paste clipboard
操作結果を確認する：画面を見る、要素を探す、ログを読む、記録する	references/observe.md	screenshot describe-ui logs record stream render-3d
アプリの実行環境を設定する	references/environment.md	location motion network interface status-bar notify shake、カメラ（WebSocket のみ）
アプリとそのデータを配置して起動する	references/apps.md	install add-media openurl schemes defaults、simctl launch

ほかに 2 つ、make docs でバイナリから生成されるファイルがあります（ここでは編集しないでください）。 references/commands.md には、すべてのサブコマンド、フラグ、終了コードが記載されています。長いファイルなので、ファイル全体ではなく、必要なコマンドのセクションを読んでください。 grep -A25 '^## baguette swipe' references/commands.md（サブコマンドは ### baguette location set の形式です）。references/wire.md には、input と WebSocket のすべての JSON ジェスチャーが記載されています。

1 回限りの操作か、ストリーミングか

少数の手順なら、ジェスチャーごとに 1 コマンド実行する方法が適しています。ただし、毎回 HID のセットアップに約 50～100 ms かかります。ドラッグ、振り付けのような一連の操作、多数の手順では、baguette input --udid <UDID> を一度起動し、1 行につき 1 つの JSON ジェスチャーを書き込んでください（references/interact.md を参照）。どちらの場合も、ok:true は操作が送信されたことを意味するだけで、画面が反応したことを示すものではありません。スクリーンショットで確認してください。

制約事項は事前に把握してください

• type／key で入力できるのは US-ASCII のキー入力です。それ以外（アクセント付き文字、CJK、絵文字）は baguette paste --text "…" を使用してください。
• press --button siri は拒否されます。既知のすべての方法で backboardd がクラッシュするためです。
• motion、network、カメラの設定が反映されるのは、それらを有効にした後に起動したアプリだけです。アプリを一度再起動してください（後から実行する network set または clear では不要です）。
• アイドル状態の画面ではフレームが出力されず、screenshot がタイムアウトすることがあります。その場合は、まずタップして画面を更新してください。
• シミュレーターのみ対応しています。実機の制御はまだ実装されていません。

スモークテスト

#!/usr/bin/env bash
set -euo pipefail
UDID="$1"
read W H < <(baguette describe-ui --udid "$UDID" | jq -r '.screen | "\(.width) \(.height)"')

baguette press --udid "$UDID" --button home
sleep 0.4
baguette tap --udid "$UDID" --x $((W * 75 / 100)) --y $((H * 55 / 100)) --width "$W" --height "$H"
sleep 0.5
baguette screenshot --udid "$UDID" --output /tmp/settings.jpg

サイズを一度取得し、すべてのジェスチャーに渡してください。位置を推測するよりも、baguette describe-ui で要素を見つけ、その中心をタップする方法がおすすめです。

Claude Code とのペアリング

SwiftUI アプリを編集するときは、ビルドして実行 → press --button home と tap で変更した画面に移動 → screenshot を撮って Read で読み取る → ピクセルが意図どおりか確認します。人間が作業の様子を追えるようにするには、baguette serve を起動して http://localhost:8421/simulators/<udid> を案内します。キーボード入力、ドラッグ＆ドロップによるインストール、機能カードにも対応しています。baguette plugin と baguette bakery でこのページを拡張できます（commands.md を参照）。

機能ごとのガイド：https://github.com/tddworks/baguette/blob/main/docs/features/<feature>/README.md。

インストール（見つからない場合のみ）

brew install baguette
baguette --version

Apple Silicon 上の Xcode 26 以降が必要です。baguette がすでに動作する場合は、この手順をスキップしてください。実行のたびに再インストールしないでください。