Ghost in the Droid

Ghost in the Droid

Invoque um fantasma no seu telefone.
Ele vê a tela. Ele toca nos botões. Ele nunca dorme.

Site · Documentação · Skill Hub · Lançamentos

_{▶ Assista em HD completo com som no YouTube · Baixar mp4}

Nove agentes. Nove dispositivos reais. Um fantasma. (Clique para assistir.)

A proposta, em uma frase

Todo agente de IA pode pensar. Quase nenhum pode tocar um telefone.

Ghost é o corpo. Ele dá a qualquer agente LLM um telefone Android ou iPhone real: ele lê a tela, toca, desliza e digita através de uma superfície de ferramentas limpa, e escala de um dispositivo na sua mesa para uma fazenda inteira de telefones. Aponte Claude Code, Codex, Antigravity, Cursor, seu aplicativo LangChain ou um modelo rodando dentro do próprio telefone para ele, e seu agente ganha mãos.

Traga seu próprio cérebro. Mantenha o mesmo corpo. MIT, para sempre.

Misture e combine: a matriz Ghost

Ghost 1.3 é o único framework de agentes Android + iOS onde plataforma, cérebro e driver são todos intercambiáveis. Escolha um de cada coluna. Todos se compõem.

_{O pool de emuladores Docker + KVM é somente Android; o iOS usa o simulador próprio da Apple e a assinatura do Xcode, que são nativos do macOS.}

O corpo permanece com as mesmas 62 ferramentas MCP, não importa o que você conecte. Cada novo lançamento de modelo é uma atualização gratuita para seu agente de telefone.

Veja em ação

Nove demonstrações, uma por recurso, cada uma gravada em dispositivos reais. Clique em qualquer clipe para o mp4 completo.

Clientes MCP: aponte seu agente para um telefone
Claude Code: digite no TUI, veja-o dirigir o telefone.	Codex: o CLI da OpenAI operando um telefone real via MCP.	Antigravity: o agente do Google, mesmo corpo de 62 ferramentas.
Interfaces: CLI, framework, navegador
Ghost CLI: ghost "check reddit" --device asus.	LangChain: as ferramentas do Ghost em um agente de framework.	Chat web: converse no seu navegador, ele dirige um telefone real.
No dispositivo e iOS: o telefone como corpo e cérebro
Android no dispositivo: o modelo roda no aplicativo, modo avião.	iPhone no dispositivo: seu iPhone fala consigo mesmo.	iPhone, aplicativo real: Ghost faz a lição do Duolingo.

O que ele faz

Framework Python de código aberto para controlar dispositivos Android e iOS a partir de um harness de agente. Android roda via ADB. iOS roda via Appium XCUITest e WebDriverAgent, com iPhones reais como caminho alvo e simuladores para desenvolvimento e CI.

Defina skills para qualquer aplicativo, execute-os a partir do painel ou API, escale em uma fazenda de telefones.

O fantasma toca no que você tocaria

• Controle Android via ADB: toque, deslize, digite, área de transferência, shell, intents e variantes furtivas
• Controle iOS via WebDriverAgent: captura de tela, árvore de acessibilidade, toque, deslize, digite, lançamento de aplicativo, área de transferência, ações do navegador
• Transmissão ao vivo da tela do telefone: Android MJPEG/WebRTC, iOS WDA MJPEG com fallback de captura de tela
• Toque interativo na tela transmitida
• Fazenda de telefones multi-dispositivo com filas de trabalho por dispositivo

Forje skills reutilizáveis para qualquer aplicativo

• Definições de elementos de UI baseadas em YAML por aplicativo
• Seletores específicos de plataforma com elements.yaml para Android e elements_ios.yaml para iOS
• Classes de ação Python com verificações de pré-condição
• Fluxos de trabalho de várias etapas que encadeiam ações
• Skills integradas para TikTok e Play Store
• Skill de demonstração de navegador/notícias iOS e fluxos de trabalho TikTok iOS de nível smoke
• Skill Hub: navegue, pesquise e instale skills do registro da comunidade
• Instale via CLI: android-agent skill install tiktok

Ensine novos truques ao fantasma

• Explorador automático de aplicativos baseado em BFS: descobre cada tela e transição
• Criador de Skill assistido por LLM: converse com IA enquanto visualiza o stream ao vivo do dispositivo
• A IA identifica elementos de UI e gera código de ação/fluxo de trabalho

Escale a assombração

• Fazenda de telefones multi-dispositivo com filas de trabalho por dispositivo
• Executor de bot: enfileire, agende e monitore trabalhos de automação
• Testes de integração por dispositivo com gravação de tela Android ou gravação iOS WDA MJPEG

Suporte de plataforma

Por que é construído assim

Skills custam $0. Pensar custa tokens. Um agente não deve pagar um LLM para tocar em um botão que já tocou mil vezes. Fluxos de trabalho conhecidos compilam em skills: receitas determinísticas em YAML + Python que são reproduzidas em segundos com zero chamadas de LLM. Use IA para a tarefa desconhecida, reproduza para a conhecida.

O telefone é a sandbox mais fácil que existe. Dê ao fantasma um Android antigo com seu próprio SIM e suas próprias contas, fisicamente separado da sua vida. Você já sabe como configurar um telefone.

Zero-app por padrão. Uma instalação nova não toca em nada no dispositivo Android: leituras de tela passam por uiautomator, ações por adb shell input, sem root, sem serviço de acessibilidade. Quer mais rápido? O aplicativo complementar opcional Portal oferece leituras de UI aproximadamente 30x mais rápidas. Quer privacidade? O modo no dispositivo executa todo o loop dentro do telefone, nada sai dele. Tudo opt-in.

Local-first, nuvem opcional. O servidor e o painel rodam na sua máquina. Com um cérebro local ou no dispositivo, suas capturas de tela nunca saem da sua rede. Escolha um cérebro na nuvem e os prompts vão para esse provedor, como qualquer ferramenta. A decisão é sua, sempre.

Requisitos

• Python 3.10+
• Android: telefone Android com depuração USB habilitada e ADB no PATH (adb devices deve listar seu telefone)
• iOS: macOS com Xcode, Appium 2 + driver XCUITest, e um iPhone confiável ou simulador iniciado
• Node.js 18+ (para o servidor de desenvolvimento do frontend)

Suporte iOS

Ghost dirige iPhones através de Appium/WebDriverAgent com a mesma superfície de ferramentas: referências de dispositivo ios:<udid> roteiam toque/deslize/digitação/captura de tela para WDA, e primitivas de navegador cientes de iOS (open_url, read_news, extract_visible_text) cobrem tarefas web. Ferramentas somente Android (shell, launch_intent, sobreposição do Portal) retornam um erro de plataforma claro em vez de falhar silenciosamente.

iOS é opt-in: habilite com GITD_ENABLE_IOS=1 (ou ios_platform_enabled=true em .env). A condução sem fio usa sua tailnet Tailscale, então trate a tailnet como o limite de confiança. Veja docs/SETUP_IOS.md para configuração do Appium/WDA, e no dispositivo no iPhone para rodar o modelo no próprio iPhone.

Início rápido

Instalação zero com uvx (ou 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 imprime uma lista de verificação com dicas de correção em vez de um stack trace quando algo está faltando (ex.: adb não está no PATH). Prefere pipx? pipx install ghost-in-the-droid fornece os comandos ghost-in-the-droid / android-agent.

Entre com sua assinatura Claude (sem chave de API)

Se você tem uma assinatura Claude Max/Pro, não precisa de chave de API. android-agent login faz login através do fluxo OAuth Anthropic do próprio CLI claude e aponta o Ghost para o provedor claude-code:

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

Ghost nunca manipula ou armazena seu token; o CLI claude é o dono dele, incluindo a renovação. doctor mostra uma verificação verde de assinatura Claude assim que você entra. Para usar uma chave de API, defina ANTHROPIC_API_KEY (ou OPENAI_API_KEY / OPENROUTER_API_KEY) e escolha esse provedor.

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

Início rápido iOS

O suporte iOS requer um Mac porque o Appium usa a pilha XCUITest/WebDriverAgent do Xcode. iPhones reais também exigem confiança, Modo de Desenvolvedor, permissão de Automação de UI quando solicitado e assinatura WDA com uma equipe de desenvolvimento Apple.

# 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

Para detalhes completos sobre assinatura em dispositivo real, simulador, WDA MJPEG, recuperação de saúde, agendador e configuração do MCP, consulte docs/SETUP_IOS.md.

Variáveis de Ambiente

Copie .env.example para .env (se fornecido) ou crie um arquivo .env na raiz do projeto. O servidor lê a configuração via Pydantic Settings. As variáveis opcionais incluem:

Dê a qualquer agente de IA um corpo móvel (MCP)

O Ghost fornece um servidor MCP com 62 ferramentas para controle de dispositivos reais. Qualquer cliente compatível com MCP pode usá-las. Seriais Android recebem a implementação Android; referências ios:<udid> roteiam para o backend iOS quando suportado e retornam erros estáveis de plataforma não suportada para ferramentas exclusivas do Android. Um comando conecta tudo:

# 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 instala o pacote, cria um ambiente isolado e executa o servidor. Sem clone, sem venv.

# 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"]
    }
  }
}

As 62 ferramentas, por categoria:

toggle_overlay, launch_intent, auxiliares de shell Android, ADB sem fio e auxiliares da Play Store permanecem exclusivos do Android e retornam erros estáveis de plataforma no iOS.

Execute o cérebro dentro do telefone

Novo na versão 1.3: o modelo pode viver no dispositivo. O aplicativo complementar do Ghost incorpora mecanismos reais de inferência, então o telefone é tanto o corpo quanto o cérebro. Modo avião ativado, o agente continua funcionando, nada sai do dispositivo.

No iPhone, o Qwen2.5 1.5B roda via llama.cpp no Metal e controla a própria interface do telefone, com um mecanismo MLX opcional para decodificação mais rápida em Apple Silicon. Modelos pequenos são mantidos honestos com decodificação restrita por gramática, para que chamadas de ferramentas sempre sejam analisadas. Detalhes completos na página de LLM no dispositivo.

CLI do Skill Hub

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

O registro de habilidades fica em registry/ neste repositório. Habilidades da comunidade são descobertas automaticamente todas as noites a partir de repositórios marcados com android-agent-skill.

Ensine ao Ghost um Novo Aplicativo

Duas maneiras de criar uma habilidade:

• Habilidade da comunidade (seu próprio repositório): crie um repositório com skill.yaml, elements.yaml, ações e fluxos de trabalho, marque-o com android-agent-skill, e ele aparecerá no Skill Hub automaticamente (coleta noturna).

• Habilidade oficial (PR para este repositório): construa e teste como uma habilidade da comunidade primeiro, depois abra um PR adicionando-a a registry/. O CI valida, um mantenedor revisa e ela recebe o selo "Oficial".

Cada habilidade precisa de:

• skill.yaml: metadados (nome, versão, pacote do aplicativo ou ID do bundle iOS, plataformas suportadas, ações, fluxos de trabalho)
• elements.yaml: IDs de recursos de elementos de interface Android e descrições
• elements_ios.yaml: seletores iOS opcionais para árvores de acessibilidade XCTest
• actions/: classes Python que estendem Action com precondition() e execute()
• workflows/: classes Python que estendem Workflow com steps()

Prefere deixar a IA fazer isso? O Skill Creator observa um fluxo de dispositivo ao vivo e gera o código de ação e fluxo de trabalho enquanto você narra. Guia completo em CONTRIBUTING.md.

O painel

Uma sala de controle local-first em http://localhost:5055 (ou :6175 em desenvolvimento). Transmissões ao vivo WebRTC e MJPEG, toque na tela, rastreamento e todas as abas abaixo.

Arquitetura

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)

O fluxo: o backend FastAPI em :5055 expõe controle de dispositivos, habilidades, bots, agendamento e streaming. O SPA Vue fala com ele via /api/*. As habilidades definem a interação por aplicativo (elementos + ações + fluxos de trabalho). Os backends de dispositivo roteiam por referência: seriais simples usam bots/common/adb.py, referências ios:<udid> usam bots/common/ios.py e Appium/WDA. O estado fica no SQLite via SQLAlchemy 2.0 e Alembic.

Benchmark (prévia)

Resultado inicial, com o relatório completo da metodologia ainda em preparação: dirigido pelo Claude Code, o Ghost completa 115 de 116 tarefas (99,1%) no AndroidWorld, o benchmark do Google Research para agentes Android, no harness upstream não modificado. Trate isso como uma prévia, não como um número citável. O relatório detalhado e as trajetórias estão por vir. Acompanhe os lançamentos.

Pilha Tecnológica

Executando Testes

A maioria dos testes são testes de unidade/API e rodam sem um dispositivo real. Testes de integração ao vivo para Android e iOS exigem a pilha de dispositivos correspondente.

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

Para testes de fumaça ao vivo no 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

Obtenha o serial do seu dispositivo Android em adb devices.

Migrações de Banco de Dados

O projeto usa Alembic para migrações de esquema:

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

Contribuindo

O ghost fica mais forte a cada habilidade. Veja CONTRIBUTING.md para adicionar habilidades de aplicativos (maior impacto), escrever ações e fluxos de trabalho, arquitetura de backend e o processo de PR. Junte-se à comunidade no Skill Hub.

Licença

MIT. O ghost é livre. O ghost é open source. O ghost é seu.