Ghost in the Droid

Ghost in the Droid

ゴーストをスマートフォンに召喚しましょう。
画面を見て、ボタンをタップします。眠ることはありません。

ウェブサイト · ドキュメント · スキルハブ · リリース

_{▶ YouTube で高画質・サウンドありの全編を見る · mp4 をダウンロード}

9 体のエージェント。9 台の実機デバイス。1 体のゴースト。（クリックして視聴。）

ひとことで言うと

AI エージェントはどれも思考できます。しかし、スマートフォンを操作できるものはほとんどありません。

Ghost はその身体です。 あらゆる LLM エージェントに、実機の Android スマートフォンまたは iPhone を与えます。使いやすいツールを通じて画面を読み取り、タップ、スワイプ、入力を行い、デスク上の 1 台からスマートフォンファーム全体まで拡張できます。Claude Code、Codex、Antigravity、Cursor、LangChain アプリ、あるいはスマートフォン自体の内部で動作するモデルを接続すれば、エージェントに手が生えます。

頭脳は自由に選べます。身体はそのまま。永久に MIT ライセンスです。

組み合わせは自由：Ghost マトリックス

Ghost 1.3 は、プラットフォーム、頭脳、ドライバーをすべて入れ替えられる、唯一の Android + iOS エージェントフレームワークです。各列から 1 つずつ選んでください。すべて組み合わせて利用できます。

_{Docker + KVM エミュレータープールは Android 専用です。iOS では Apple 独自のシミュレーターと Xcode 署名を使用するため、macOS が必要です。}

何を接続しても、身体を構成する 62 個の MCP ツールは変わりません。新しいモデルがリリースされるたびに、スマートフォンエージェントを無料でアップグレードできます。

実際の動作を見る

各機能を1つずつ紹介する9本のデモです。すべて実機で録画しています。クリップをクリックすると、mp4全編を視聴できます。

MCP クライアント：エージェントをスマートフォンに接続
Claude Code：TUIに入力すると、スマートフォンが操作される様子を確認できます。	Codex：MCP経由で実機を操作するOpenAIのCLIです。	Antigravity：Googleのエージェントも、同じ62種類のツールを利用します。
インターフェース：CLI、フレームワーク、ブラウザー
Ghost CLI：ghost "check reddit" --device asus。	LangChain：フレームワークのエージェントでGhostのツールを利用します。	Webチャット：ブラウザーでチャットすると、実機が操作されます。
デバイス上とiOS：スマートフォンを身体にも頭脳にも
デバイス上のAndroid：モデルはアプリ内で動作し、機内モードでも使えます。	デバイス上のiPhone：iPhoneが自分自身と会話します。	iPhoneで実際のアプリ：GhostがDuolingoのレッスンを進めます。

できること

1つのエージェントハーネスから Android と iOS デバイスを操作する、オープンソースの Python フレームワークです。Android は ADB 経由で動作します。iOS は Appium XCUITest と WebDriverAgent 経由で動作し、実機の iPhone を主な対象としつつ、開発や CI にはシミュレーターを利用できます。

あらゆるアプリ向けのスキルを定義し、ダッシュボードや API から実行して、スマートフォンファーム全体に展開できます。

ゴーストがあなたと同じようにタップします

• ADB 経由の Android 操作：タップ、スワイプ、入力、クリップボード、シェル、インテント、ステルス機能
• WebDriverAgent 経由の iOS 操作：スクリーンショット、アクセシビリティツリー、タップ、スワイプ、入力、アプリの起動、クリップボード、ブラウザー操作
• スマートフォン画面のライブストリーミング：Android の MJPEG／WebRTC、iOS の WDA MJPEG とスクリーンショットによるフォールバック
• ストリーミング画面上で、タッチしてタップできるインタラクティブ操作
• デバイスごとのジョブキューを備えたマルチデバイスのスマートフォンファーム

あらゆるアプリ向けに再利用可能なスキルを作成

• アプリごとに UI 要素を YAML で定義
• Android 用の elements.yaml と iOS 用の elements_ios.yaml による、プラットフォーム固有のセレクター
• 前提条件をチェックする Python アクションクラス
• 複数のアクションを連結するマルチステップワークフロー
• TikTok と Play Store 向けの組み込みスキル
• iOS のブラウザー／ニュースデモスキルと、スモークテストレベルの TikTok iOS ワークフロー
• Skill Hub：コミュニティレジストリでスキルを閲覧、検索、インストール
• CLI からインストール：android-agent skill install tiktok

ゴーストに新しい技を教える

• BFS ベースの自動アプリ探索機能：すべての画面と画面遷移を検出
• LLM 支援のスキル作成ツール：デバイスのライブストリームを見ながら AI とチャット
• AI が UI 要素を特定し、アクションやワークフローのコードを生成

怪奇現象をスケールさせる

• デバイスごとのジョブキューを備えたマルチデバイスのスマートフォンファーム
• ボットランナー：自動化ジョブのキュー登録、スケジュール設定、監視
• Android の画面録画または iOS の WDA MJPEG 録画を使った、デバイスごとの統合テスト

プラットフォームサポート

このような設計にした理由

スキルのコストは 0 ドル。思考にはトークンが必要です。 エージェントは、何千回もタップしたことのあるボタンをタップするために LLM を使うべきではありません。既知のワークフローはスキルとしてコンパイルします。決定論的な YAML と Python のレシピを使い、LLM を一切呼び出さずに数秒で再実行できます。未知のタスクには AI を使い、既知のタスクは再実行します。

スマートフォンは最も手軽なサンドボックスです。 自分専用の SIM とアカウントを設定した古い Android をゴーストに与え、自分の生活環境とは物理的に分けて使えます。スマートフォンのセットアップ方法は、すでにご存じでしょう。

デフォルトではアプリ不要です。 新規インストールしても、Android デバイスには何も手を加えません。画面の読み取りには uiautomator、操作には adb shell input を使い、root もアクセシビリティサービスも必要ありません。もっと高速にしたいですか？ オプションの Portal コンパニオンアプリを使うと、UI の読み取り速度が約 30 倍になります。プライバシーを重視しますか？ オンデバイスモードでは処理全体がスマートフォン内で完結し、外部にデータが送信されません。どちらもオプトイン方式です。

ローカルファーストで、クラウドは任意です。 サーバーとダッシュボードはご利用のマシンで動作します。ローカルまたはオンデバイスの AI を使えば、スクリーンショットがネットワークの外に出ることはありません。クラウドの AI を選んだ場合は、他のツールと同じようにプロンプトがそのプロバイダーに送信されます。すべては常にご自身で選択できます。

要件

• Python 3.10以降
• Android：USBデバッグを有効にしたAndroidスマートフォンと、PATH上にあるADB（adb devicesを実行するとスマートフォンが一覧に表示されます）
• iOS：Xcodeを搭載したmacOS、Appium 2とXCUITestドライバー、信頼済みのiPhoneまたは起動済みのシミュレーター
• Node.js 18以降（フロントエンドの開発サーバー用）

iOSのサポート

GhostはAppium/WebDriverAgentを介してiPhoneを操作します。ツールのインターフェースは共通です。ios:<udid>のデバイス参照を指定すると、タップ／スワイプ／入力／スクリーンショットがWDAに送られ、iOS対応のブラウザープリミティブ（open_url、read_news、extract_visible_text）でWebタスクを実行できます。Android専用ツール（shell、launch_intent、Portalオーバーレイ）は、黙って失敗するのではなく、プラットフォームエラーを明示します。

iOSの利用はオプトインです。GITD_ENABLE_IOS=1（または.envのios_platform_enabled=true）で有効にしてください。ワイヤレス操作はTailscaleのテールネットを経由するため、テールネットを信頼境界として扱ってください。Appium/WDAのセットアップについてはdocs/SETUP_IOS.mdを参照してください。また、モデルをiPhone自体で実行するには、iPhone上でのオンデバイス実行を参照してください。

クイックスタート

uvx（またはpipx）を使えば、インストールせずに実行できます。

uvx ghost-in-the-droid doctor   # green/red preflight: python, adb on PATH, devices, ports, LLM keys
uvx ghost-in-the-droid login    # sign in with your Claude subscription, no API key needed
uvx ghost-in-the-droid up       # server + dashboard at http://localhost:5055  (API docs at /docs)

doctorは、何かが見つからない場合（例：PATH上にadbがない場合）、スタックトレースの代わりに、修正のヒント付きチェックリストを表示します。pipxを使いますか？pipx install ghost-in-the-droidを実行すると、ghost-in-the-droid／android-agentコマンドを利用できます。

Claudeサブスクリプションでサインインする（APIキー不要）

Claude Max/Proサブスクリプションをお持ちの場合、APIキーは不要です。android-agent loginを実行すると、claude CLI独自のAnthropic OAuthフローを通じてサインインし、Ghostがclaude-codeプロバイダーを使うように設定されます。

android-agent login       # opens Anthropic sign-in via the claude CLI

Ghostがトークンを扱ったり保存したりすることはありません。更新も含め、トークンはclaude CLIが管理します。サインインすると、doctorに緑色のClaudeサブスクリプションチェックが表示されます。代わりにAPIキーを使うには、ANTHROPIC_API_KEY（またはOPENAI_API_KEY／OPENROUTER_API_KEY）を設定し、そのプロバイダーを選択してください。

brew install ollama       # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull llama3.2:3b   # 2GB, fast, good tool-use

git clone https://github.com/ghost-in-the-droid/android-agent.git
cd android-agent
pip install -e ".[all]"

android-agent doctor        # preflight
android-agent up            # start server + dashboard on :5055

# Frontend (separate terminal)
cd frontend && npm install && npx vite --host 0.0.0.0 --port 6175
# Dashboard at http://localhost:6175

iOSクイックスタート

AppiumはXcodeのXCUITest/WebDriverAgentスタックを使用するため、iOSのサポートにはMacが必要です。実機のiPhoneでは、信頼設定、デベロッパモード、プロンプトが表示された際のUIオートメーションの許可、およびAppleの開発チームによるWDAの署名も必要です。

# 1. Install and run Appium XCUITest
npm install -g appium
appium driver install xcuitest
appium --base-path /

# 2. Find your iPhone or booted simulator UDID
xcrun xctrace list devices
xcrun simctl list devices booted

# 3. Configure the backend for iOS
export IOS_DEVICE_UDID="<udid>"
export IOS_APPIUM_URL="http://127.0.0.1:4723"
export IOS_BUNDLE_ID="com.google.chrome.ios"       # or com.apple.mobilesafari
export IOS_MJPEG_SERVER_PORT="9100"                # use unique ports per iOS device

# 4. Run a product-path smoke workflow
uv run python scripts/ios_chrome_news_smoke.py \
  --device "ios:<udid>" \
  --bundle-id "$IOS_BUNDLE_ID" \
  --url https://text.npr.org/ \
  --max-headlines 5 \
  --max-articles 3 \
  --fix-health \
  --out-dir data/ios_chrome_news_smoke

実機の署名、シミュレーター、WDA MJPEG、ヘルスリカバリー、スケジューラー、MCPのセットアップについて詳しくは、docs/SETUP_IOS.mdを参照してください。

環境変数

.env.exampleがある場合は.envにコピーするか、プロジェクトのルートに.envファイルを作成してください。サーバーはPydantic Settingsを介して設定を読み込みます。任意の環境変数は次のとおりです。

あらゆる AI エージェントにモバイルの身体を与える（MCP）

Ghost には、実機を操作する 62 個のツールを備えた MCP サーバーが同梱されています。MCP 互換のクライアントであれば、どれでも利用できます。Android のシリアル番号には Android 実装が適用され、ios:<udid> の参照は、対応している場合は iOS バックエンドに振り分けられ、Android 専用ツールの場合は安定した非対応プラットフォームエラーが返されます。コマンドひとつで設定できます。

# Claude Code (same shape for Codex, Cursor, VS Code Copilot, Windsurf)
claude mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

uvx がパッケージをインストールし、分離された環境を構築して、サーバーを実行します。リポジトリのクローンも、仮想環境の作成も不要です。

# Codex (OpenAI)
codex mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

{
  "mcpServers": {
    "android-agent": {
      "command": "uvx",
      "args": ["--from", "ghost-in-the-droid", "android-agent-mcp"]
    }
  }
}

カテゴリ別の 62 個のツール：

toggle_overlay、launch_intent、Android シェルヘルパー、ワイヤレス ADB、Play ストアヘルパーは引き続き Android 専用で、iOS では安定したプラットフォームエラーが返されます。

脳をスマートフォン内で動かす

1.3 の新機能：モデルを デバイス上で 動かせます。Ghost コンパニオンアプリには実際の推論エンジンが組み込まれているため、スマートフォンが身体と脳の両方になります。機内モードをオンにしても、エージェントは動作し続け、デバイス外にデータが出ることはありません。

iPhone では、Qwen2.5 1.5B が Metal 上の llama.cpp を通じて動作し、スマートフォン自身の UI を操作します。また、Apple Silicon でより高速にデコードできるオプトインの MLX エンジンも用意されています。小型モデルでもツール呼び出しが常に正しく解析されるよう、文法制約付きデコードで出力を制御します。詳しくはオンデバイス LLM のページをご覧ください。

Skill Hub CLI

android-agent skill search tiktok        # search the public registry
android-agent skill install tiktok       # install a skill
android-agent skill install github.com/someone/their-skill
android-agent skill list                 # what is installed
android-agent skill update tiktok        # update a skill
android-agent skill validate ./my-skill/ # check before publishing

スキルレジストリは、このリポジトリの registry/ にあります。android-agent-skill タグが付いたリポジトリから、コミュニティのスキルが毎晩自動的に検出されます。

Ghost に新しいアプリを教える

スキルの作成方法は 2 つあります。

コミュニティスキル（独自のリポジトリ）：skill.yaml、elements.yaml、アクション、ワークフローを含むリポジトリを作成し、android-agent-skill タグを付けると、スキルハブに自動で表示されます（スクレイパーが毎晩実行されます）。

公式スキル（このリポジトリへの PR）：まずコミュニティスキルとして作成・テストしてから、registry/ に追加する PR を作成します。CI による検証後、メンテナーがレビューし、「Official」バッジが付与されます。

各スキルには以下が必要です。

• skill.yaml：メタデータ（名前、バージョン、アプリのパッケージまたは iOS のバンドル ID、対応プラットフォーム、アクション、ワークフロー）
• elements.yaml：Android UI の要素リソース ID と説明
• elements_ios.yaml：XCTest のアクセシビリティツリー用の iOS セレクター（任意）
• actions/：precondition() と execute() を実装する Action の Python クラス
• workflows/：steps() を実装する Workflow の Python クラス

AI に任せたいですか？ Skill Creator はライブデバイスストリームを監視し、説明に合わせてアクションとワークフローのコードを生成します。詳しくは CONTRIBUTING.md をご覧ください。

ダッシュボード

http://localhost:5055（開発環境では :6175）で利用できる、ローカル優先のコントロールルームです。WebRTC と MJPEG によるライブストリーム、画面上のタップ、トレースに加え、以下のタブを備えています。

アーキテクチャ

android-agent/
  run.py                    # Uvicorn entry point on :5055
  gitd/
    app.py                  # FastAPI app factory + plugin hook
    models/  schemas/       # SQLAlchemy 2.0 ORM + Pydantic v2
    routers/  services/     # Route handlers + business logic
    skills/                 # Skill packages (tiktok, play_store, safari [iOS], tiktok_ios)
    bots/common/adb.py      # Android Device class: tap, swipe, dump tree, wait_for
    bots/common/ios.py      # iOS Device class: Appium/WDA session, UI tree, gestures
    mcp_server.py           # MCP server: 62 tools for any LLM agent
  frontend/                 # Vue 3 + Vite + TypeScript + Tailwind
  portal/                   # Kotlin companion app (WebRTC, on-device inference)
  site/                     # Docs site (Astro + Starlight)

処理の流れ： :5055 で動作する FastAPI バックエンドが、デバイス制御、スキル、ボット、スケジューリング、ストリーミングを提供します。Vue SPA は /api/* 経由でバックエンドと通信します。スキルはアプリごとの操作（要素 + アクション + ワークフロー）を定義します。デバイスバックエンドは参照情報に応じて振り分けます。通常のシリアル番号には bots/common/adb.py を、ios:<udid> 形式の参照には Appium/WDA と bots/common/ios.py を使用します。状態は SQLAlchemy 2.0 と Alembic を介して SQLite に保存されます。

ベンチマーク（先行公開）

詳細な方法論の執筆は進行中ですが、初期結果では、Claude Code を使った Ghost は、変更されていない上流のハーネスで、Android エージェント向けの Google Research のベンチマークである AndroidWorld の 116 タスク中 115 件（99.1%） を完了しました。引用可能な数値ではなく、プレビューとしてお受け取りください。詳細なレポートと実行軌跡は近日公開予定です。リリースをご確認ください。

技術スタック

テストの実行

テストの大半はユニットテスト／API テストで、実機がなくても実行できます。Android と iOS の実機統合テストには、それぞれ対応するデバイススタックが必要です。

# Run all tests on a specific device
DEVICE=<serial> python3 -m pytest tests/ -v --tb=short

iOS の実機スモークテストを実行するには：

IOS_LIVE_NEWS_TEST=1 \
IOS_DEVICE_UDID="<udid>" \
IOS_APPIUM_URL="http://127.0.0.1:4723" \
IOS_BUNDLE_ID="com.google.chrome.ios" \
uv run --extra test python -m pytest tests/test_browser_news.py::test_live_ios_chrome_news_workflow

Android デバイスのシリアル番号は adb devices で確認できます。

データベースのマイグレーション

このプロジェクトでは、スキーマのマイグレーションに Alembic を使用します。

alembic revision --autogenerate -m "add new_field to my_table"   # after editing a model
alembic upgrade head                                              # apply pending
alembic downgrade -1                                              # rollback one

コントリビューション

スキルを追加するたびに、ゴーストは強くなります。アプリスキルの追加（最も大きな効果があります）、アクションとワークフローの作成、バックエンドのアーキテクチャ、PR の手順については、CONTRIBUTING.md をご覧ください。Skill Hub でコミュニティに参加しましょう。

ライセンス

MIT です。ゴーストは無料です。ゴーストはオープンソースです。ゴーストはあなたのものです。