Give any LLM agent a real Android or iPhone as its body. 62 MCP tools for mobile automation.
Early result, with the full methodology writeup still cooking: driven by Claude Code, Ghost completes 115 of 116 tasks (99.1%) on AndroidWorld, Google Research's benchmark for Android agents, on the unmodified upstream harness. Treat this as a preview rather than a citable number. The detailed writeup and trajectories are coming. Watch the releases.
| Layer | Technology |
|---|---|
| Backend | FastAPI, Uvicorn, Python 3.10+ |
| Data | SQLAlchemy 2.0, Alembic, Pydantic v2, SQLite (WAL) |
| Frontend | Vue 3, TypeScript, Vite, Tailwind CSS 4 |
| Device control | ADB for Android; Appium XCUITest/WebDriverAgent for iOS |
| Streaming | Android MJPEG/WebRTC via Portal; iOS WDA MJPEG plus screenshot fallback |
| On-device | llama.cpp, MediaPipe (Android); llama.cpp on Metal, MLX (iOS) |
| Quality | Ruff, pytest, Playwright |
Most tests are unit/API tests and run without a live device. Live Android and iOS integration tests require the relevant device stack.
# Run all tests on a specific device
DEVICE=<serial> python3 -m pytest tests/ -v --tb=short
For iOS live smoke tests:
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
Get your Android device serial from adb devices.
The project uses Alembic for schema migrations:
alembic revision --autogenerate -m "add new_field to my_table" # after editing a model
alembic upgrade head # apply pending
alembic downgrade -1 # rollback one
The ghost gets stronger with every skill. See CONTRIBUTING.md for adding app skills (highest impact), writing actions and workflows, backend architecture, and the PR process. Join the community on the Skill Hub.
MIT. The ghost is free. The ghost is open source. The ghost is yours.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx ghost-in-the-droidMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-ghost-in-the-droid-android-agent": {
"command": "uvx",
"args": [
"ghost-in-the-droid"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceghost-in-the-droidpypiGhost in the Droid works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.