artemis

Let AI assistants and test suites use real phones like a human.

English • 中文文档 • Workflow Showcase • Quick Start • MCP for IDEs • Benchmarks • Discord Community

Live Demo: Setup driving routes and calculate total durations in Google Maps, then open YouTube to play a Coldplay song.

✨ Key Highlights

• 🤖 Cross-App Automation & Autonomous AI Assistant: Operates not just as a robust testing framework, but as an autonomous agent capable of handling complex cross-app workflows and daily tasks via natural language;
• 🧪 Zero-Maintenance Test Automation: Built upon a "Dynamic-First, Coordinate-Fallback" multimodal locating engine, eliminating fragile XPath/ID selector maintenance and remaining resilient to UI redesigns, system updates, and resolution drift;
• 🐞 One-Click Bug Repro & Logcat Diagnostics in IDE: Native Model Context Protocol (MCP) integration allows Antigravity, Claude Code, and Windsurf to drive physical test devices via natural language, automatically capturing crash stacks from Logcat and keyframe screenshots;
• ⚡ Ultra-Fast Execution (3–5s per Step): Pioneered an Optimistic Asynchronous Pipeline that completely decouples UI interaction from heavy LLM reasoning, achieving rapid regression throughput in Flash mode;
• 🛡️ Popup Self-Healing & 10+ Hour Exploration: Proprietary Safety Net double-checks targets before action execution to intercept and clear interfering system popups; Pro mode supports 10+ hours of continuous exploratory & monkey-plus stability testing;
• 🏆 Industry-Leading SOTA: Achieved 99%+ task completion on Google Research's AndroidWorld benchmark (100+ complex multi-step tasks).

🤝 Antigravity × ARTEMIS: Autonomous Testing Workflow

Experience seamless collaboration between Antigravity and ARTEMIS via native MCP integration — taking you from a natural language requirement to a production-grade diagnostic report in four automated steps:

1️⃣ Prompt Input (Task Dispatch) Describe your test scenario and target metrics in Antigravity	2️⃣ Test Plan Generation Formulates a step-by-step test plan & architecture for review
3️⃣ Autonomous Test Execution Drives real device, navigates UI, and profiles performance	4️⃣ Comprehensive Final Report Delivers structured audit findings, metric tables, and raw datasets

⚡ Quick Start

Ensure an Android device (with USB Debugging enabled) or emulator is connected. The one-click startup script will automatically:

• 🛠️ Install System Toolchains: Detect and auto-install ADB, scrcpy, FFmpeg, and Python (uv) dependencies.
• 🔌 Mount Global MCP Server & AI Agent Rules: Prompt to automatically install global MCP configurations and the Artemis Mobile Testing Mindset (rules.md) into your AI IDEs (Antigravity, Cursor, Claude Code, Codex, Windsurf, VS Code, Cline/Roo, OpenClaw).

🍎 macOS and 🐧 Linux

# 1. Clone repo & navigate to directory
git clone https://github.com/google/artemis.git && cd artemis

# 2. One-click launch
./start.sh

🪟 Windows PowerShell

# 1. Clone repo & navigate to directory
git clone https://github.com/google/artemis.git
cd artemis

# 2. One-click launch
.\start.bat

PowerShell does not search the current directory for executable scripts by default, so use .\start.bat without a trailing \. In Command Prompt (CMD), use start.bat instead.

💡 Tip: Opens http://localhost:8000 in your default browser with a device connection wizard, live screen mirroring, prompt sandbox, and execution replays. You can also run directly from CLI: uv run artemis run "Open Settings, find Battery and tell me current level" --profile flash.

# Auto-install MCP server & global rules for Antigravity / Jetski:
uv run artemis mcp --install antigravity

# Or install for all supported AI IDEs (including Codex):
uv run artemis mcp --install all

[mcp_servers.artemis]
command = "/path/to/artemis/.venv/bin/python"
args = ["-m", "mcp_server"]
cwd = "/path/to/artemis"

[mcp_servers.artemis.env]
PYTHONUNBUFFERED = "1"
PYTHONPATH = "/path/to/artemis"

{
  "mcpServers": {
    "artemis": {
      "command": "/path/to/artemis/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/artemis",
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "tools": {
        "mobile_run_task": { "eager": true },
        "mobile_manage_task": { "eager": true },
        "mobile_get_device_state": { "eager": true },
        "mobile_inspect_trace": { "eager": true }
      }
    }
  }
}

{
  "mcpServers": {
    "artemis": {
      "command": "/path/to/artemis/.venv/bin/python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/artemis"
    }
  }
}

import asyncio
from artemis.interfaces.sdk import ArtemisClient


async def main():
    # Initialize client (choose "flash" for fast UI checks or "pro" for deep reasoning & self-healing)
    client = ArtemisClient(default_profile="flash")

    # Execute natural language end-to-end test case
    result = await client.run(
        "Open System Settings, go to 'Battery', verify battery percentage is displayed, and check for any crash dialogs."
    )

    # Structured assertions & execution tracing
    assert result.status == "SUCCESS", f"Test failed: {result.failure_reason}"
    print(f"✅ Test Passed! Turns: {result.turns} | Trace ID: {result.trace_id}")


if __name__ == "__main__":
    asyncio.run(main())

🕹️ Usage Modes

_{💡 Console Overview: ① View Switcher (Home / Workspace) · ② Model & Replay (Flash/Pro status & video replay) · ③ Live Agent Stream (Action perception, target coordinates & structured results) · ④ Prompt Dock (Natural language dispatch) · ⑤ Task Queue & Dashboard (Lifecycle & history)}

• 🖥️ Web Visual Test Console (uv run artemis ui): Real-time screen projection and interactive panel, supporting natural language test dispatch, live reasoning telemetry, action trajectories, and execution replay;
• 🔌 Native MCP Protocol (IDE Collaboration): Operates as a standard MCP server seamlessly integrating with Antigravity, Claude Code, Windsurf, etc., directly driving real devices inside the IDE to verify bugs and run test cases;
• 💻 Developer CLI (uv run artemis run): Direct terminal execution for automated test cases, exploratory stability inspection, or AndroidWorld benchmarks with high-fidelity structured terminal output;
• 🐍 Python SDK: Integrates as a standard Python library into existing automated testing frameworks (e.g., pytest) or CI/CD pipelines with strongly typed Pydantic structured outputs and assertion support.

📊 Head-to-Head Comparison

🏆 Benchmarks: AndroidWorld (SOTA 99%+)

Evaluated on AndroidWorld — Google Research's gold-standard benchmark spanning 20+ real apps and 100+ complex multi-step tasks: Artemis demonstrated exceptional robustness across the entire benchmark suite, achieving a 99%+ completion rate.

🚀 How ARTEMIS is Architected

• ⚡ Optimistic Asynchronous Pipeline: The front-facing loop responds in milliseconds, while memory pruning and assertion verification run concurrently in the background without blocking execution;
• 🛡️ Safety Net Pre-Execution Gate: Dual-layer pre-check validates target availability milliseconds before action dispatch, instantly intercepting unexpected popups to eliminate blind clicks;
• ⏱️ Time-Sensitive Speculative Chaining: Overcomes LLM inference latency for transient UI elements (e.g. video fullscreen) by predicting target coordinates and executing rapid chained taps.

⚡ Execution Profiles: Flash vs. Pro

🗺️ Roadmap

• Optimistic Asynchronous Pipeline: Ultra-lean main loop + background context compression & milestone checks.
• Pre-Execution Safety Net: Millisecond pre-check gate & speculative chained actions.
• Time-Sensitive Media Tasks: Fullscreen video and audio stream analysis with scrcpy & ffmpeg.
• Native MCP Server: Seamless integration with tools like Antigravity and Claude Desktop.
• Web Visual Console: Live screen projection, interactive playground, and trajectory review.
• AndroidWorld SOTA: Achieved 99%+ task completion rate.
• Cross-Platform Extensions: Exploring iOS and desktop Web perception and execution.
• On-Device Lightweight VLMs: Zero-cloud local execution with lightweight edge vision models.
• Real-time Duplex Voice Mode: Natural voice input with real-time interruption (barge-in) control.

🤝 Community & Contributing

Contributions are warmly welcomed!

• ⭐ Star the repo to follow updates and releases
• 💬 Join the Discord Community for technical discussions
• 🐛 Open an Issue or submit a Pull Request

📄 License

This project is licensed under the Apache License 2.0.