qirabot 2.0.3

AI vision-driven GUI automation across browsers, mobile, desktop, and games

Qirabot Python SDK

Cross-platform GUI automation, driven by multimodal AI vision. Drive browsers, mobile apps, full desktops, and games through pixels — no DOM, no selectors — reaching what frameworks like Playwright, Selenium, and Appium cannot.

Run it standalone (bot.open() launches a browser for you; Android / iOS / Windows-window backends are built in with zero extra dependencies), bolt it onto your existing Playwright / Selenium / Appium / pyautogui session, drop it into a pytest suite, or bind by HWND to drive a Unity / Unreal / native desktop game. Same API across all of them.

📖 Full documentation: qirabot.com/docs (中文)

Installation

One line — installs uv, qirabot (isolated, never touches your system Python), and Chromium. No pre-installed Python required:

# macOS / Linux
curl -LsSf https://qirabot.com/install | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://qirabot.com/install.ps1 | iex"

Driving a device instead of a browser? The Android (adb), iOS (WDA), and Windows single-window backends are built into the core package:

uv tool install qirabot        # Android + iOS + Windows window; zero extras

pip, virtualenvs, per-framework extras, and troubleshooting: Installation guide. Whichever path you took, qirabot doctor reports what is installed, what is missing (with the exact fix), and whether your API key reaches the server.

Quick Start

Save your API key once (get it from your dashboard), then hand the AI a task:

qirabot login
qirabot browser "Search for SpaceX and get the first sentence of the article" --url wikipedia.org

The same task through the Python SDK — bot.ai() is the same engine: the AI looks at the screen, decides the next action, and loops until the task is done:

from qirabot import Qirabot

bot = Qirabot()
page = bot.open("https://www.wikipedia.org")

result = bot.ai(page, "Search for SpaceX and get the first sentence of the article")
print(f"Success: {result.success}")
print(f"Result: {result.output}")

bot.close()

Prefer to drive each step yourself? The same natural-language targeting works as single-step calls — bot.click(page, "Login button"), bot.extract(...), bot.verify(...) — with your code in control. Every run writes an HTML report with per-step screenshots; --record captures a video.

Bolt onto your existing stack

No rewrite: pass your existing page / driver / device object and mix AI steps with the selectors you already have —

from qirabot import Qirabot

bot = Qirabot(task_name="test-checkout")

def test_checkout(page):          # your existing pytest-playwright fixture
    page.goto("https://shop.example.com")
    page.fill("#username", "test_user")             # your selectors, as-is
    page.click("#login-btn")

    assert bot.verify(page, "Product listing page is displayed")   # AI assertion

    result = bot.ai(page, "Complete checkout, name John Doe zip 10001", max_steps=8)
    assert result.success

Works the same for Selenium, Appium, pyautogui, and the built-in device backends (AdbDevice, WdaClient, Window) — and anything else via a 7-primitive custom adapter.

Documentation

Topic
Getting started	Installation · Quick Start · CLI Reference
Platform backends	Browser · Android (adb, no Appium) · iOS (WDA, no Appium) · Windows & Games (DirectInput) · Desktop · Custom Adapters
Framework bolt-on	Playwright · Selenium · Appium · pytest
Advanced	AI Tasks & Custom Tools · Reports & Recording · Configuration · Error Handling
Reference	API — Actions & Platform Matrix

Examples

Runnable examples live in examples/, in three styles:

• Bolt onto your existing tests (pytest) — playwright/, selenium/, appium/, desktop/
• Standalone automation (plain scripts) — scraping / RPA / agents: automation/
• Drive a desktop game (Windows) — bind by HWND, deterministic steps + bot.ai(): game/

See examples/README.md for which to pick.

Agent Skill

plugins/qirabot/skills/qirabot/ is a pre-built agent skill: an AI agent (Claude Code, Cursor, …) loads it and handles setup, scripting, and verification from a natural-language automation goal. Install in Claude Code:

/plugin marketplace add qirabot/claude-plugins
/plugin install qirabot@qirabot

The skill's reference and templates are drift-tested against the live SDK in CI (tests/test_skill.py). Details: plugins/qirabot/README.md.

Migrating from 1.x (airtest)

2.0 removed the airtest integration; the built-in backends are drop-in replacements (AdbDevice / WdaClient / Window), and a copyable adapter keeps existing airtest scripts running unchanged. Guide: Custom Adapters — Migrating from Airtest. The 1.x series lives on the 1.x branch in maintenance mode — pip install "qirabot<2" always resolves to the newest 1.9.x patch.

License

MIT