simframe

simframe

iOS Simulator や Android エミュレーターを操作するコーディングエージェントの目、手、記憶です。 エージェントはタップ位置付きのテキストとして画面を読み取り、1 回の呼び出しで一連の操作を実行し、これまでに見た画面を記憶します。そのため、手順ごとにスクリーンショットを撮り、モデルを往復させて、画面を読み直す必要がなくなります。

同じアプリのセッションを、ごくわずかなトークン数で実行できます。 実際の React Native のフィールドアプリで、エージェントは 2 つの作業を最初から最後まで実行し、実際に送信しました。サービスリクエストの作成と、アセットの追加です。1 回の実行ごとの測定値です。2026-10-03：

操作したもの	両方の作業を完了	ツール呼び出し	スクリーンショット	トークン数
simframe なしで、Claude Code 組み込みのシミュレーターツールを使った Opus	はい	約176	112	296k
simframe を使った Opus	サービスリクエスト（セッションがアセットのアップロードを阻止）	約50	≥4	118k
simframe を使い、Sonnet のドライバーに指示を出す Opus（プラグインのドライバーエージェント）	はい	約88	少数	128k（より安価なモデル）

同じモデルで simframe を使用した場合と使用しない場合を比べると、トークン数は 2.5 倍減り、呼び出し回数は 3.5 倍減りました。 Sonnet のドライバーは、simframe なしの実行で行ったすべての作業を、トークン数を 2.3 倍減らし、呼び出し回数を半分にして、112 枚を撮影した場面でも数枚の画像だけで実行しました。各構成につき 1 回の実行のみなので、これは測定例としてご覧ください。測定値の詳細と、示していない点については、docs/BENCHMARKS.mdをご覧ください。まだ人間並みの速度には遠く、その差も測定されています。 アプリを知っている人が同じ 2 つの作業を約 1.5 分で完了しました（5 回の実行の中央値は 39 秒と 49 秒です）。エージェントは 13～16 分かかり、9～10 倍遅くなりました。これは、エージェントが各手順を読み取り検証し、モデルの応答ごとに数秒かかるためです。1 つのフローあたりの応答回数を減らし、記憶からフローを再実行できるようにすることが、ロードマップの目標です。

10秒でインストール

シミュレーターを使っている場合はすでにお持ちの、Xcodeを搭載したMacとNode 18以降が必要です。 それ以外は何も必要ありません。idbもAppiumもPythonも不要です。

Claude Code — プラグインとしてインストールすると、MCP サーバーと、プロトコルを説明する スキルをまとめて導入できます。

claude plugin marketplace add lvlrSajjad/simframe
claude plugin install simframe@simframe

または、MCP サーバーのみをインストールします。

claude mcp add --scope user simframe -- npx -y simframe mcp

プラグインにはドライバーエージェント（simframe:simframe-driver）も含まれています。メインセッションから目標を渡すと、simframe のツールだけを使って Sonnet で操作し、短いレポートを返します。simframe に限定されているため、小さなモデルでも使えます。すべてのツールを使える状態では、Haiku は使えませんでした。**ドライバーには、上記のプラグインのインストールが必要です。**プラグイン独自のツール名に接続されているため、claude mcp addだけで追加したサーバーでは利用できません。

どちらか一方を選んでください。両方インストールすると、2つのサーバーが同じデバイスを操作することになります。以前にclaude mcp addで追加していた場合は、先にclaude mcp remove simframeを実行してください。

Claude Desktop —「設定」→「開発者」→「設定を編集」を開き、次を追加します。

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

Cursor — または、同じsimframeブロックを~/.cursor/mcp.jsonに追加します。

Codex、Windsurf、Zed、VS Codeなど、MCPに対応するもの — 同じJSONブロックを、クライアントのmcpServersが保存されている場所に追加します。

次にシミュレーターを起動し、エージェントに何か頼んでみましょう。「アプリを開いて、サインアップの流れを進めて」、「Ordersタブのリストは読み込み中ですか？」、*「Saveボタンを押しても何も起きないのはなぜ？」*などです。最初の呼び出しでは、ソースから小さなSwiftデーモンをビルドします。所要時間は約15秒で、ビルドは一度だけです。

CLIはエージェントを介さずに同じ操作を行うもので、インストールの確認に最適な、最も手軽な方法です。

npm install -g simframe
simframe doctor          # every layer, and which engine carries it
simframe ui              # the current screen as a numbered text map

複数のシミュレーターが起動している場合は、--device=<udid>またはexport SIMFRAME_DEVICE=<udid>で対象を指定してください。間違ったデバイスを操作するコマンドがタップであるため、simframe は推測による選択を行いません。

変更点

エージェントがシミュレーターを操作すると時間がかかる理由は3つあります。明らかなのはそのうち1つだけです。画面を見るたびに待ち時間が発生します（simctl io screenshotには約130 msかかり、見るたびにその時間が加算されます）。各ステップではモデルとの往復が発生します。そして何も記憶されないため、同じ画面が表示されるたびに、再び読み取り、推論し直します。さらに、まったく無駄な点がもう1つあります。画面に何が表示されているかを知るには画像が最もコストの高い方法であり、それでもどこをタップできるかは分かりません。

	simframe なし	simframe あり
画面を見る	約130～400 msのスクリーンショット。処理をブロック	約20 ms。すでにキャプチャ済み
「何か変わった？」	画像全体	約2 ms。テキストのみ
画面を読む	画像。約1,600トークン。タップ位置なし	約330トークンのテキスト。タップ位置付き
10ステップのフロー	10ターン、10枚の画像	1ターン、画像0枚
同じフローをもう一度	毎回、初回と同じ	記憶から再生し、各ステップを検証。モデル呼び出し0回
アプリで実際に2つのタスクを行うセッション	約176回の呼び出し、112枚のスクリーンショット、296kトークン	約50回の呼び出し、118kトークン（同じモデル）

iPhone 17 Proシミュレーター、iOS 26.5、Apple Siliconで、実際の本番アプリを使って測定しました。N、中央値、p95を含む表全体は docs/BENCHMARKS.mdにあります。

画像の代わりに、エージェントには次の情報が返されます。

iPhone 17 Pro · 402x874pt · screen a1b2c3d4 "Inbox" (known, 3 known exits)
last action: [2] tap — ok: matches the outcome seen 5x before
nav-bar:
  #1 button    24,64      Back
  #2 text      201,64     Inbox
content:
  #3 cell      201,140    Weekly digest
  #4 field     201,196    Search = weekly ~ weekly|
  #5 switch    201,252    Notifications = 1
tab-bar:
  #6 text      62,835     Inbox
  #7 text      201,835    Settings
next: settled; nothing ambiguous — chain the next steps in one sim_do without looking again.

領域、種類、ラベル、内容、タップ位置、そして次の呼び出しでセレクターとして使える番号です。= valueはアクセシビリティツリーが示すコントロールの値、~ valueはOCRがピクセルから読み取った値です。両者が食い違うところに、注目すべき点があります。

ツール

ツール	機能
sim_ui	まずはこちらから。 上記の番号付きテキストマップとして画面を表示します。
sim_do	メインのツールです。 タップ、入力、スクロール、待機、検証を、各ステップが完了してから次に進み、前回の動作結果と照合しながら、1 回の呼び出しで一連のフローとして実行します。代替セレクター、任意のステップ、範囲を限定した seek により、予期しない事態が起きてもバッチを中断して制御を戻すことなく続行できます。
sim_state	前回の確認から変化があったか、どの領域が動いたかを確認します。
sim_goto · sim_flow_run	simframe が以前に訪れた画面へ移動します。保存したフローはモデル呼び出しなしで再生します。
sim_goal	到達先を指定すると、simframe がローカルで操作し、マイルストーンに到達した時点で結果を返します。完了（証拠あり）、障害物によるブロック、あいまい、または未検出のいずれかです。
sim_map	アプリを無人で巡回します。デフォルトでは読み取り専用で、すべての画面と遷移を記録するため、後の作業を記憶に基づいて実行できます。検証の障壁を越えたり、アプリを離れたりすることはありません。
sim_find · sim_tap · sim_type_into · sim_scroll_to · sim_wait_for · sim_assert	単一の操作のみを行う場合のための、個別のアクションです。
sim_launch · sim_open_url · sim_permission	アプリを起動（前面に表示されたことを確認）し、ディープリンクを開き、アラートをタップせずにプライバシー権限を付与します。
sim_look	画像を返す唯一のツールです。 最大 1024 px で、レイアウト、色、余白を確認します。
sim_recall · sim_strip · sim_storage	直近 1 分間の出来事をテキストまたはコンタクトシートで確認します。また、デバイスの電源が切れていても、アプリが保存した内容（UserDefaults、AsyncStorage）を確認できます。
sim_wait · sim_capture · sim_devices	変化が起きてから安定するまで待機します。キャプチャを管理し、シミュレーターとエミュレーターを一覧表示します。

コントロールの指定方法は 3 通りあり、どの方法も名前が付けられた場所で使えます。"Save"（意図から解決します。動詞、タイプミス、同義語、一般的な名称でのアイコンのみのコントロールに対応）、#3（マップで付けられた番号。その画面でのみ有効）、または @120,400（生の座標。最後の手段）です。削除につながる語彙（Delete、Pay、Send、Sign out）に一致するラベルは、決して代用されたり推測されたりしません。

パッケージには Claude Code スキルが含まれており、CLI の使い方を説明します。こちらはさらに低コストです。ツールの結果の代わりに数行の出力で済み、ツールを使うまで MCP スキーマがコンテキストに入りません。

Android

2 つ目のバックエンドでは、同じコマンド、同じ画面マップ、同じメモリを使って Android エミュレーターを操作します。フレームはエミュレーターコンソール経由で約 41 ms で届き、タップ、スワイプ、テキスト、キー、クリップボードを使えます。simframe devices はエミュレーターをシミュレーターと並べて一覧表示します。Android にはアクセシビリティツリーがないため、画面の読み取りは OCR と CV のみで行われます。simframe doctor はその事実を隠さずに示します。詳細、コスト、根拠についてはガイドをご覧ください。

仕組みの概要

デバイスごとに 1 つの Swift デーモンが動作します。ディスプレイが損傷を報告すると、シミュレーターのフレームバッファーを IOSurface から直接読み取り、同じサーフェス上で Apple の Vision OCR を実行し、ホスト側でアクセシビリティツリーを読み取り、HID チャネル経由でタップを実際の down/move/up シーケンスとして送信します。PNG もファイルも、起動されるプロセスもありません。フレームは ~/.simframe/<udid>/ に保存され、入力は 0600 の Unix ソケット経由で送信されます。MCP サーバーと CLI は、どちらも両者を利用する薄いクライアントです。

画面メモリは、統合された要素マップを構造的フィンガープリントでキー付けするため、以前に見た画面はファイルを読み込むだけで済みます。遷移グラフには、どの画面からどの画面へ、どのアクションで移動したかが記録されます。そのため、sim_goto は経路を計画でき、保存したフローはモデルを介さずに再生できます。

どのレイヤーも失敗するのではなく、機能を縮退させながら動作し、その際も必ず明示します。simframe doctor は各レイヤーの状態を報告し、--strict を指定すると、どのような縮退もゼロ以外の終了コードになります。デーモンがリンクするプライベートフレームワークについては、根拠とともに docs/PRIVATE_API.md に記載されています。

詳細はこちら

docs/GUIDE.md	完全ガイド：往復通信なしでの復旧、画面メモリーと2つのハッシュ、メモリーを使ったナビゲーション、CLI、応答しなくなったシミュレーターの診断、セッションのコストを抑える方法、ロードマップ
docs/BENCHMARKS.md	N、中央値、p95、マシン、測定時の落とし穴を含む、すべての数値
docs/EXPERIMENTS.md	測定前に信じていたことと、それが覆った14回の実験
docs/DECISIONS.md	計画を変えた判断。独自の測定によって中止されたフェーズも含みます
docs/DEFERRED.md	既知の不具合すべて。未解決・解決済みを問わず、根拠も記載しています
docs/ARTICLE.md	エージェントは瞬きをしてはいけない — すべての成果をまとめた主張

ここでの判断はほぼすべて、議論ではなく測定に基づいており、すでにリリースした判断が測定によって覆ったことも何度かあります。主な成果は2つです。ウォーム状態の遷移グラフによって、エージェントのモデルとの往復通信が約27％削減されます。また、デーモンがすでに計算している値に対する1行のしきい値判定が、ステップ監視に試したすべてのローカルモデルを上回りました。精度は95％対77〜91％で、レイテンシーはゼロです。

制限事項

• シミュレーターとエミュレーターのみが対象です。物理デバイスにはアクセスできません。
• デーモンは非公開のフレームワークにリンクしています。iOS 26への移行では問題ありませんでしたが、Xcodeをアップグレードするとシンボルが移動する可能性があります。doctorは問題のあるレイヤーを示し、--engine=screenshotは引き続き動作します。
• Androidにはアクセシビリティツリーがないため、画面の識別はOCRのジオメトリーのみに依存します。iOSより情報が少なく、ノイズも多くなります。
• ハードウェアボタンはhomeのみです。他のコードは未検証で、誤ったコードを使うとデバイスがクラッシュする可能性があるため、推測せずエラーを返します。
• 確認に使う語句（OK、Save、Doneなど）は英語です。
• 修正の確認は速くなりますが、問題の特定は速くなりません。古いクロージャー内のバグは、どのフレームにも表示されません。

各項目の根拠となる測定結果を含む全リストは、ガイドを参照してください。

リリース

バージョンを上げる方法はnpm versionのみです。そのフックによってserver.jsonも同期されます。また、git push --follow-tagsを実行すると、シークレットなしでnpmと公式MCP Registryに公開するワークフローが実行されます。この仕組みを採用した理由と、かつて1週間にわたって消えていたリリースについては、ガイドを参照してください。

ライセンス

MIT