Browser Automation

Qirabot drives the browser through pixels rather than the DOM. The AI reads the rendered page the way a person does, so it works where selector-based automation breaks: canvas apps, cross-origin iframes, shadow DOM, aggressive A/B-tested layouts, and pages that change faster than your test suite.

You can let Qirabot manage the browser, or bolt it onto the Playwright / Selenium session you already have.

Managed browser

Requires the browser extra: uv pip install "qirabot[browser]" then qirabot install-browser.

The quickest way to see it run is a single CLI command, with no code:

qirabot browser "Open the top story and summarize the discussion" --url news.ycombinator.com
qirabot browser "..." --headless --viewport 1920x1080
qirabot browser "..." --user-data-dir ~/.qira-profile --channel chrome   # logins survive runs
qirabot browser "..." --cdp-url http://localhost:9222                    # attach to running Chrome

--cdp-url also works with remote pools like browserless.

Log in once, reuse the session

For sites that need an account, set the login up by hand. This step runs no AI task, so no model calls are made and no tokens are spent. open-browser opens the profile in a visible browser; log in, close the window, and every later run that passes the same --user-data-dir starts already signed in:

qirabot open-browser --user-data-dir ~/.qira-profile --url news.ycombinator.com/login
# log in in the window, then close it
qirabot browser "Open the top story and summarize the discussion" --user-data-dir ~/.qira-profile

A profile directory can't be shared by two browsers at once, so close the login window before running tasks. For login walls the AI hits mid-task (captchas, 2FA), see human-in-the-loop.

The same run through the SDK: bot.open() launches Chromium (Playwright under the hood), and you write no framework code yourself:

from qirabot import Qirabot

bot = Qirabot()
page = bot.open("https://news.ycombinator.com")

result = bot.ai(page, "Open the top story and summarize the discussion")
print(result.output)

bot.close()

bot.open() takes the same knobs as the CLI flags above: headless=True, viewport=(1920, 1080), channel="chrome", extra Chromium args=[...], cdp_url="http://localhost:9222" to attach to a running Chrome instead of launching one, and user_data_dir="~/.qira-profile" to reuse the profile you logged into with open-browser (~ is expanded on every platform).

Bolt onto the session you already have

If you already run a browser through your own framework, skip bot.open() and pass your own object as the target, or bind() it once to stop repeating it (bind() is covered in Custom Adapters & Bolt-On):

• Playwright: pass your page; mix your selectors with AI steps freely. Full guide: Playwright + Qirabot.
• Selenium: pass (or bind()) your driver. Selenium is not bundled as an extra, so install it yourself (uv pip install qirabot selenium). Full guide: Selenium + Qirabot.
• pytest: AI assertions and AI steps inside your existing suite, with fixtures and CI notes. Full guide: pytest + Qirabot.

One gotcha worth knowing up front: a click can open a new tab, and the returned page is the live one, so keep the form page = bot.click(page, ...). Details and the smart go_back behavior are in the API reference.

Notes

• Headless detection: on a display-less box (no DISPLAY), bot.open() and the CLI automatically run headless, with a warning. open-browser is the exception: it errors out instead, since a browser nobody can see is useless for manual login.
• close_tab is Playwright-only; navigate, go_back, press_key (including ctrl+w to close the current tab; reassign the returned page), and scroll all work. See the full per-platform action matrix in the API Reference.