crewdroid

crewdroid

AI エージェント向けのヘッドレス Android デバイスラボです。 1 つのコマンドでさまざまな Galaxy エミュレーターのフリートを起動し、それぞれのネットワークを異なるスケジュールで切断して、同じユーザーフローを異なるタイミングで再生し、サーバーのデータを調べて並行処理のバグ（レコードの重複、欠落、上書き）を判定します。ウィンドウもクリック操作も不要です。すべての手順は --json と終了コードを返す CLI コマンドであり、同じコマンドが MCP ツールとエージェントスキルとしても使えます。

npx crewdroid up --count 3        # 3 devices: s24ultra/API 34, fold5/API 34, flip7/API 36 — booted in ~7 s each
npx crewdroid run scenarios/photo-upload.json --seed 1   # multi-user flow + network chaos + judge, exit 1 on a bug

Android Emulator だけではだめなのでしょうか？

標準のエミュレーターは、手作業で操作するウィンドウ付きの 1 台のスマートフォンです。crewdroid はプログラムで操作する フリート です。

	Android Emulator / AVD Manager	crewdroid
デバイス	1 つの AVD につきウィンドウが 1 つ、ディスクイメージも 1 つ	1 つのベースイメージから作成した N 個の読み取り専用クローン。画面サイズ（S／Fold／Flip／任意の WxH@dpi）と API レベルを混在させ、1 つのコマンドで起動
操作	ウィンドウ内をクリックし、スクリーンショットを読む	すべてのコマンドが --json 出力と終了コードを返す。screen はピクセル画像の代わりにアクセシビリティツリーを返す
起動	コールド起動で 31.6 秒	スリムスナップショットから 6.7 秒
ディスク	24.7 GiB（AVD 3 台）	6.99 GiB（クローン 3 台、API レベル 3 種類）
ホスト RAM	8.45 GB	3.93 GB
アイドル時 CPU（100 % = 1 コア）	1000 %	約 600 %
ネットワーク	Extended Controls で 1 つの切り替え	デバイスごとに airplane、nodata、slow、flaky をランダムなスケジュールで切り替え、アップロード中にも実行
マルチユーザーのバグ	機能なし	run が異なるタイミングで全デバイス上のフローを繰り返し、その後 judge がサーバーをチェック：unique、count、noLostUpdate
デバイスの状態	GUI パネル	env（GPS、バッテリー、回転、ダークモード、フォント、ロケール、GSM、SMS、通話）と app（権限、ディープリンク、Doze、trim、ストレージ容量不足）。各設定後に状態を読み戻して確認
Fold／Flip	折りたたみ式 AVD が必要	任意のクローンで fold／unfold を実行：アプリに実際の構成変更が通知される
AI エージェント向け	呼び出せるものなし	MCP サーバー、AGENTS.md、症状（「アプリがクラッシュした」「ディープリンクが開かない」「同期で行が重複した」）に応じて起動する 7 つのスキル

数値は、Windows 11 PC 1 台（Ryzen 7 5700X、64 GB、WHPX）で、デバイス 3 台を使い、標準の google_apis AVD 3 台と比較して測定しました。生の JSON と測定方法は docs/measurements/ を参照してください。

意図的に障壁は設けていません。実際の並行処理バグは、ボタンをまったく同じミリ秒に押すことでなく、再試行、オフラインキュー、遅れて行われる編集が重なることで発生します。crewdroid は各デバイスにそれぞれ異なる遅延とネットワークスケジュールを設定し、処理が重なるようにしてから、サーバーの実データを読み取ります（ADR 0002）。

60 秒で概要を確認

異なる種類のデバイスを含むフリートを起動します（ヘッドレスで、画面には何も表示されません）。

$ crewdroid up --count 3 --json
[
  { "serial": "emulator-5580", "profile": "s24ultra",   "api": 34, "screen": "1080x2340@450", "bootSeconds": 6.4, "readySeconds": 42.1 },
  { "serial": "emulator-5582", "profile": "fold5-main", "api": 34, "screen": "1812x2176@420", "bootSeconds": 6.7, "readySeconds": 41.8 },
  { "serial": "emulator-5584", "profile": "flip7-main", "api": 36, "screen": "1080x2520@480", "bootSeconds": 3.1, "readySeconds": 39.9 }
]

1 台のデバイスでアップロード中にデータ通信を切断し、別のデバイスでは接続を不安定にします。

$ crewdroid net emulator-5580 nodata
$ crewdroid net emulator-5582 flaky

競合状態のあるサーバー（同梱のサンプルサーバーでは BUGGY=1）に対してマルチユーザーのシナリオを実行し、判定結果を確認します。

$ crewdroid run scenarios/photo-upload.json --seed 1
...
VIOLATION uploads unique(key): duplicate key="u13-1" (2 rows)
VIOLATION uploads count(acks): missing 1 of 48 expected key values
VIOLATION writes noLostUpdate(id,baseVersion): lost update: 3 writes to id="r2" all based on baseVersion=4; all but one were overwritten
FAIL: 5 violations            # exit code 1

同じシナリオでも、サーバーを修正すれば OK: 3 rules, 0 violations となり、終了コードは 0 です。判定ルールは JSON ファイルなので、自分の API のエクスポートに対しても同じチェックを実行できます。

スクリーンショットを使わずに、画面に何が表示されているかを尋ねます。

$ crewdroid screen emulator-5580 --json
{ "focused": "dev.crewdroid.probe/.ProbeActivity",
  "tree": [ { "cls": "TextView", "text": "outbox: 1 pending", "bounds": [32,180,620,230], "clickable": false, "depth": 3 }, ... ] }

エージェント向けに設計

• すべてのコマンドが機械可読です：--json、失敗時はゼロ以外の終了コード、各セッターの実行後に読み戻し、不正な入力の場合は adb を呼び出す前に明確なエラーを表示します。
• MCP サーバー：crewdroid mcp は stdio 経由で devices、up、down、net、env、app、fold、triage、screen、perf、apk、judge、hammer、run を公開します。CLI が呼び出す関数と同じものを使用し、別個の実装はありません。
• .agents/skills/ にある スキル（Claude Code、Cursor、Gemini CLI、Copilot、Codex が読み込みます）：crewdroid、android-triage、android-screen、android-permissions-intents、android-apk、android-perf、android-offline-concurrency。それぞれ、エージェントが出力に基づいて動作できる、正確なコマンドをまとめた短い手順です。
• AGENTS.md にはエージェントが守るべきルール（adb の対象は emulator-<port> のみ、同時に実行するのは 1 つまで、バリアは使用しない）を記載し、Claude Code 向けに CLAUDE.md も用意しています。
• 共有マシンでも安全です：同じ PC に USB 接続されたスマートフォンには一切触れません。クローンは読み取り専用で、down が終了させるのは crew-* のみです。

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

claude plugin marketplace add namyunsu/crewdroid && claude plugin install crewdroid@crewdroid

Cursor：MCP サーバーをインストール · Codex / Gemini CLI / Copilot：スキルと AGENTS.md はリポジトリから読み込まれます。

検出できる問題

バグの種類	crewdroid による再現方法	検出するルール
再試行後のアップロード重複（冪等性の欠如）	flaky ネットワークで応答が失われ、アプリの送信待ちキューが同じキーで再試行します	unique(key)
レコードの欠落（再起動／機内モードで送信待ちキューが失われる）	保存中に airplane を有効にし、オフラインでアプリを再起動してから再接続します	count(acks)
更新の消失（2 人のユーザーが同じ行を編集し、後から書き込んだ方が優先される）	デバイスが異なるタイミングで同じバージョンを読み取り、両方が PUT します	noLostUpdate(id,baseVersion)
アップロード中の折りたたみ	送信待ちキューの処理中に fold / unfold を実行します。アプリは設定変更に耐え、アップロードを 1 回だけ実行する必要があります	unique + count
特定の Android バージョンまたは画面でのみ発生するクラッシュ／ANR	1 回の実行で API 31/34/36 と S/Fold/Flip のプロファイルを組み合わせます。triage がクラッシュバッファー、ANR、終了理由を読み取ります	—

同梱のサンプルアプリ（Kotlin、オフライン送信待ちキュー、probe-app/）とサンプルサーバー（sample/server/、BUGGY=1 スイッチ）を使うと、上記のすべてをノート PC 上で再現できます。

要件

• コマンドラインツールと emulator >= 36.4 を備えた Android SDK（ANDROID_SDK_ROOT または ANDROID_HOME が SDK を指しているか、~/.crewdroid/android-sdk が存在する必要があります）。SDK がまだない場合：npx crewdroid setup --yes を実行すると、JDK 17（sdkmanager 専用）、コマンドラインツール、platform-tools、emulator、google_atd イメージをインストールします（--images 34,31,36、--dry-run を指定すると、まずサイズを一覧表示します）。crewdroid は、ホスト CPU 向けの必要な google_atd イメージ（x86_64、または Apple Silicon / ARM Linux では arm64-v8a、API 31/34/36、各約 0.9 GB）をダウンロードし、slim で縮小します
• Node >= 22
• Windows 10/11 x64、Apple Silicon 搭載の macOS、または Linux x64/arm64
• ハードウェアアクセラレーション：WHPX（Windows）、Hypervisor.framework（macOS）、または KVM（Linux、/dev/kvm）。setup は emulator -accel-check の結果を報告します
• macOS/Linux：slim は NTFS のスパース化／圧縮処理をスキップします（スナップショットのゼロ埋めと古いオーバーレイのクリーンアップは引き続き実行します）。RAM の値はプロセスの RSS です（共有ページは分離されません）

コマンド

すべてのコマンドは --json を受け取り、失敗するとゼロ以外の終了コードで終了します。

コマンド	説明
crewdroid up --count N [--profiles a,b] [--screen WxH[@dpi],...] [--profiles-file f.json]	Galaxy プロファイルまたは独自の画面サイズ（任意のサイズ。例：--screen 3840x2160@320）で N 台のエミュレーターを起動します
crewdroid down	すべての crew-* エミュレーターを終了します
crewdroid net <serial> airplane|nodata|slow|flaky|online	1 台のデバイスのネットワーク状態を設定します
crewdroid fold <serial> / unfold <serial>	Fold／Flip プロファイルのカバースクリーンとメイン画面を切り替えます
crewdroid run <scenario.json> [--seed N]	複数デバイスのシナリオを実行し、サーバーのデータを判定します
crewdroid judge --rules <file> --source <url|file>	unique／count／noLostUpdate ルールをチェックします
crewdroid hammer --url <base>	デバイスを使わずにサーバー側の並行負荷をテストします
crewdroid slim / prepare / identity	ディスク容量を削減し、ベース AVD を構築し、デバイスを個別化します
crewdroid measure --up N	ディスク容量、RAM、起動時間、アイドル時の CPU 使用率を測定します
crewdroid triage / screen / perf / apk	Android の診断を行います。以下を参照してください
crewdroid env <serial> <what> [args]	デバイス環境：位置情報、バッテリー、画面の向き、ダークモード、フォント、ロケール、モバイルネットワーク、SMS、通話（「環境」を参照）
crewdroid app <serial> <pkg> <what> [args]	アプリ制御：権限、ディープリンク／App Links、データ消去、バックアップ／復元、リソース負荷（「アプリ制御」を参照）
crewdroid shot / tap / type / swipe / key	mobile-mcp を使わずにスクリーンショットを撮影し、入力します（「スクリーンショットと入力」を参照）
crewdroid mcp	上記の機能をエージェントに公開する stdio MCP サーバー

スクリーンショットと入力

コマンド	説明
crewdroid shot <serial> [file.png]	exec-out screencap -p で file.png に保存します（デフォルト：./crewdroid-<serial>-<yyyymmdd-HHMMSS>.png）。パス、幅 x 高さ、blackRelaunch を出力します（API 31 の黒画面を最初に復旧します。screen と同様です）。MCP ツールは PNG を画像コンテンツとして返し、テキストを 1 行出力します。
crewdroid tap <serial> <x> <y> | --text <T> | --id <resource-id> [--index N]	指定した座標、または screen ツリー内でテキスト／content-desc または resource-id（全体、または :id/ 以降の部分）が一致する要素の中央を input tap でタップします。一致判定は、まず完全一致を試し、その後、大文字と小文字を区別しない部分一致を試します。一致しない場合、または --index（0 始まり）を指定せずに複数一致した場合は、候補（テキスト、id、範囲）を表示して終了コード 1 で終了します。
crewdroid type <serial> <text> [--into <text|id>]	input text を実行します（スペース、引用符、&、% はエスケープされます）。--into を指定すると、先にフィールドをタップします。ASCII 文字のみ対応しています。以下を参照してください。
crewdroid swipe <serial> up|down|left|right [--times N] | swipe <serial> x1 y1 x2 y2 [ms]	現在の画面の中央 50％の範囲で指定した方向にスワイプします（up はコンテンツを下にスクロールします）。
crewdroid key <serial> back|home|enter|delete|tab|menu|KEYCODE_*	input keyevent を実行し、その後、フォーカスされているウィンドウを出力します。

画面外の座標を指定すると、何も送信する前に終了コード 1 で終了します。ASCII 以外のテキスト（韓国語など）は入力されません。type はその理由を示して終了コード 1 で終了します。input text で入力できるのはデバイスのキーマップにある文字のみです。ATD には貼り付け用のクリップボードを設定するシェルコマンドがありません（cmd clipboard は実装されていません）。また、crewdroid はキーボードアプリをインストールしません。そのようなテキストはアプリ経由（intent extra、テストフック）で渡すか、ADBKeyboard などの IME を自分でインストールしてください。プローブアプリには、これらを試すフォームがあります：--es check form（フィールド id name、ボタン Send → CrewProbe FORM <text>。3 画面分のスクロールがあり、最下部の END で CrewProbe SCROLL END がログに記録されます）。node scripts/check-input.mjs を実行すると、API 34 と API 36 のデバイスですべての動作を確認できます。

診断

読み取り専用のコマンドです（デバイス上で実行状態が残ることはありません）。各コマンドで --json を指定できます。同じ4つのコマンドが MCP ツールでもあります。

コマンド	出力
crewdroid triage <serial> [--app <pkg>] [--heap out.hprof]	crashes（logcat のクラッシュバッファー：パッケージ、例外、アプリ内の最上位フレーム、時刻）、anrs（ActivityManager のログと dumpsys activity exit-info）、anrTraces（/data/anr のヘッダー。root 権限がない場合は "unreadable"）、exits（終了理由）、recentLog（アプリの直近200行）、summary。--heap を指定すると am dumpheap を実行して hprof を取得します。
crewdroid screen <serial> [--png file]	フォーカス中のウィンドウ（dumpsys window）と、コンパクトな uiautomator ツリー [{cls, text, desc, id, bounds, clickable, depth}]。Compose の testTag は testTagsAsResourceId = true の場合にのみ id として表示されます。API 31 でアプリの再起動後に画面が完全に黒くなった場合（Android 12 エミュレーターのバグ。どのツールの am start -S でも発生）は、先に復旧（HOME + 再開）し、blackRelaunch として報告するため、アプリのバグと誤認されることはありません。
crewdroid perf <serial> <pkg> [--activity .Main] [-- <am start extras>]	コールドスタート（am force-stop、2秒、am start -W。TotalTime ms）、フレーム数／ジャンク率／dumpsys gfxinfo による p50-p90-p99、dumpsys meminfo による PSS の合計／Java／ネイティブ（KB）。ATD イメージには GPU がないため、スマートフォンとの比較ではなく、実行間でフレーム数を比較してください。
crewdroid apk <file.apk>	ホスト上のみ（最新の build-tools の aapt2 を使用）：パッケージ、バージョン、min/target SDK、権限、エクスポートされたアクティビティ、ディープリンクフィルター。

プローブアプリにはこれらのターゲットがあります：adb -s emulator-5580 shell am start -n dev.crewdroid.probe/.ProbeActivity --es check crash|anr|jank（anr：ボタンをタップし、10秒以内にもう一度タップします）。node scripts/check-triage.mjs は、1台の API 34 デバイスですべてのコマンドを実行します。

環境

crewdroid env <serial> <what> [args] [--json]。すべての設定コマンドは状態を読み戻し、異なっている場合はメッセージを表示して終了コード 1 で終了します。不正な値（battery 150、rotate 9、emulator-<port> 形式ではないシリアル番号）は、adb を呼び出す前に終了コード 1 で終了します。MCP ツール（env）としても利用できます。

内容	意味
geo <lon> <lat> [alt]	GPS の位置情報（経度が先）を設定し、位置情報をオンにします。Android が位置情報を受け取るのは、アプリが位置情報を要求している間だけです。そのため、設定値との不一致では設定コマンドは失敗せず、位置情報がオンかどうかだけを確認し、Android が最後に認識した位置情報を報告します（androidLastFix、delivered）。位置情報が確認されるのは、プローブの ENV loc= 行（check=env）だけです
`battery <0-100> [ac	unplugged]`
rotate <0-3>	自動回転をオフにし、回転を固定します
sensor acceleration x:y:z	加速度計の値
`dark on	off/font `
locale <pkg> <tags>	アプリごとのロケール。例：locale dev.crewdroid.probe ko-KR,en。API 33 以降のみ対応（デバイス全体のロケールを設定するシェルコマンドはありません）
`gsm data home	roaming
gsm signal <0-31> [--hold <sec>]	電波強度。コンソールでは 15 秒間保持されます。--hold を指定すると 10 秒ごとに再送します。読み戻し機能はありません（コンソールの確認応答のみ）
sms <from> <text> / `call [accept	cancel]`
show	上記すべての状態をデバイスから読み戻します

rotate は wm fixed-to-user-rotation enabled も実行します。これを実行しないと、API 36 イメージでは次回のアプリ起動時に WindowManager が以前の回転状態を復元します（revertOverride）。rotate と show は、設定と WindowManager からロック状態を読み戻します。gsm signal はコンソールの OK のみで確認されます（読み戻し機能はありません）。負の数も指定できます（env emulator-5580 geo -122.084 37.422）。ATD には Messages アプリも Dialer アプリもありません。SMS と通話では、テレフォニーの状態とブロードキャストのみが変化します。プローブアプリは認識した内容をログに記録します。am start -n dev.crewdroid.probe/.ProbeActivity --es check env -> CrewProbe ENV dark=<bool> font=<scale> rot=<n> battery=<pct> loc=<lat>,<lon>|none（loc には位置情報の権限が必要です：pm grant）。node scripts/check-env.mjs は 2 台のデバイスですべてを実行します。

アプリの制御

crewdroid app <serial> <pkg> <what> [args] [--json]。設定コマンドは状態を読み戻し、異なる場合はメッセージを表示して終了コード 1 で終了します。不正な名前、バケット、サイズの場合は、adb を呼び出す前に終了コード 1 で終了します。MCP ツール（app）としても利用できます。

内容	説明
`perm grant	revoke <perm…>/perm show [perm…]`
open <uri> [--pkg]	am start -a VIEW -c BROWSABLE -d <uri>（--pkg：このパッケージのみ）。処理できるアクティビティがない場合は終了コード 1 で No Activity found（ATD には Chrome がありません）。アプリの実行中は、そのタスクが前面に表示されるだけで URI は渡されません。結果には delivered: false と表示されます。先に強制停止してください
links show / links force <domain> / links reset	アプリリンク（API 31 以降）：pm get-app-links、set-app-links --package <pkg> 2 <domain>（インターネット接続なしで承認）、... 0 all
clear	pm clear。run-as で状態を読み戻します（デバッグ可能なアプリ）。それ以外は pm の Success のみを確認します
backup / restore	com.android.localtransport/.LocalTransport を使った bmgr（API 34 と 36 のイメージにはあります。存在しない場合は、その理由を示して終了コード 1 で終了します）。データがないアプリの backup はトランスポートに拒否されます。restore は最新のセットを使用します
pressure doze / `standby <active	working_set
pressure trim <level>	am send-trim-memory（HIDDEN ... COMPLETE）。デバイス上での読み戻しはなく、am の応答のみを確認します。バックグラウンドレベルをフォアグラウンドプロセスに適用する場合、またはプロセスが実行されていない場合はエラーになります。プローブは CrewProbe TRIM <level> をログに記録します
pressure reset	doze、バッテリーの接続解除、スタンバイバケット（-> active）、bg-restrict、battery-saver を元に戻します
fill-storage <GB> / fill-storage free	/data/local/tmp に fallocate でファイルを作成し、df -k /data で状態を読み戻します。free はファイルを削除します。イメージには約 5.8 GB の空きがあります

プローブアプリには、ディープリンク crewdroid://probe/* と https://probe.crewdroid.example/*（autoVerify）があり、CrewProbe LINK <uri> をログに記録します。node scripts/check-app.mjs は 2 台のデバイスですべてを実行します。

デバイスプロファイルの追加

プロファイルは起動後に wm size / wm density で適用する画面（幅 x 高さ、密度）であり、別個の AVD ではありません。profiles/galaxy.json にエントリーを追加します。

{ "name": "s25", "model": "Galaxy S25", "width": 1080, "height": 2340, "density": 420, "minAndroid": "15", "minApi": 35 }

次に crewdroid up --count 1 --profiles s25 を実行します。minApi によって、デバイスが使用する Android イメージが決まります。

このファイルを編集せずに任意のサイズを指定できます：crewdroid up --count 2 --screen 1920x720@160,3840x2160@320（密度は省略可能です。短辺が約 360dp になるように導出されます）。または --profiles-file my.json を指定します（スキーマは同じです。profiles/custom.example.json を参照）。ホストのモニターを超えるサイズも使用できます。7680x2160 までテスト済みです。docs/measurements/size.md を参照してください。

安全ルール

• すべての adb 呼び出しは、emulator-<port> のシリアルのみを受け付けるガードを通るため、同じマシンに接続された USB スマートフォンに触れることはありません。
• エミュレーターはベース AVD の読み取り専用クローンとして実行されるため、変更は保存されず、down は crew-* インスタンスのみを削除します。
• 1 台のマシンで同時に実行できる crewdroid は 1 つだけです（up / down はロックを取得します）。
• SDK のパスは ANDROID_SDK_ROOT / ANDROID_HOME のみから取得し、ハードコードされていません。

軽量さを維持する仕組み

ベースとなる AVD を複製（-read-only）し、システムイメージをスパース化して NTFS 圧縮します。クイックブートの RAM イメージはスナップショット前にゼロ埋めし、ゲスト RAM は 896 MB で -lowram を使用します。ホスト側の Vulkan は無効にし、オーディオとウィンドウも使用しません。各設定は一つずつ測定しました：docs/measurements/slim.md（ディスク）、ram.md（RAM）、features.md（各ランタイム機能のアイドル時のコスト — デーモンを追加するものはありません）。

韓国語のドキュメント：README.ko.md · ライセンス：MIT

キーワード：Android エミュレーター、ヘッドレス、マルチデバイステスト、並行性テスト、競合状態、冪等性、更新の消失、オフラインファースト同期、不安定なネットワーク、Galaxy Fold Flip プロファイル、MCP サーバー、AI エージェント、Claude Code プラグイン、エージェントスキル、モバイル QA 自動化。