AutoQAI documentation

AutoQAI lets an AI coding agent drive the browser tab you already have open and signed into. This guide walks through installing the MCP server and the extension, registering AutoQAI with your agent, pairing a tab, configuring a project, and running your first tests.

AutoQAI is two parts that work together: the MCP server (an npm package that runs locally inside your project) and a browser extension. Your AI agent connects to the server using the Model Context Protocol; the server relays each instruction to the extension, which executes it against your tab.

How it works

The agent never launches a browser. Instead, three pieces cooperate over a private loopback connection that never leaves your machine:

Because the extension acts inside your existing tab, your cookies, SSO session, and feature flags stay exactly as they are — the agent tests the real application the way you actually use it.

Requirements

• Node.js 22 or newer — the MCP server is published as an ESM package and runs on your machine.
• A Chromium-based browser — Google Chrome (and other Chromium browsers) are supported through the extension.
• An MCP-capable AI agent — Claude Code, Cursor, GitHub Copilot (agent mode in VS Code), or Kiro.
• A project folder — AutoQAI keeps per-project state in a local .autoqai directory, so run it from your repository root.

Install the MCP server

The server ships as the @autoqai/mcp package and exposes an autoqai command. Installing it globally is the simplest option:

npm install -g @autoqai/mcp

Confirm it installed correctly:

autoqai --version

The package is published on npm: @autoqai/mcp.

Install the browser extension

The extension is what actually drives your tab. Install it from the Chrome Web Store:

1. Open the Chrome Web Store listing and click  Add to Chrome.
2. Pin the AutoQAI icon to your toolbar so the pairing popover is one click away.
3. When you later bind a tab, Chrome shows its standard "is being debugged" banner — that's expected and confirms the tab is connected. Leave it in place while testing.

Register AutoQAI with your agent

AutoQAI can write its own MCP registration into your agent's config. Run the init command and it detects supported clients and adds the server entry:

autoqai init

You can also target specific clients or preview the changes first:

# Register with a specific client
autoqai init --client claude-code

# Register with several at once
autoqai init --client claude-code --client cursor

# Write project-scoped config instead of user-scoped
autoqai init --project

# Preview the changes without writing anything
autoqai init --dry-run

Per-client setup commands

Pick your agent below for the exact command and the manual config if you'd rather edit the file yourself.

autoqai init --client claude-code

{
  "mcpServers": {
    "autoqai": {
      "command": "autoqai"
    }
  }
}

Once registered, most agents start the autoqai server automatically when you open the project.

Uninstall

To stop an agent from loading AutoQAI, run the uninstall command — the exact reverse of autoqai init. With no arguments it removes the registration from every supported client at user scope:

autoqai uninstall

You can target specific clients, scope it to a project, or preview the changes first:

# Remove from a specific client
autoqai uninstall --client claude-code

# Remove from several at once
autoqai uninstall --client claude-code --client cursor

# Remove a project-scoped registration instead of user-scoped
autoqai uninstall --project

# Preview what would be removed without writing anything
autoqai uninstall --dry-run

• It deletes only the autoqai entry under each client's MCP server map and leaves every other server and setting in the file untouched.
• If removing autoqai leaves the server map empty, the now-empty key is removed too. A file with no autoqai entry is reported as no change.
• This does not touch any project's .autoqai folder — delete that by hand if you also want to remove a project's runs, queue, and config.
• Restart the affected agent(s) afterwards so they stop loading the AutoQAI server.

uninit and deinit are accepted as aliases for uninstall.

Pair a tab with the guided menu

The simplest way to set up a project is the interactive menu. Run autoqai with no arguments from a terminal in your project root:

# From your project root, in a terminal
autoqai

AutoQAI opens a guided menu that walks you through everything — registering it with your AI client, pairing the extension, and listing your projects:

? What would you like to do?
  Use ↑↓ to move, Enter to choose, Ctrl-C/Esc to go back.
> Register globally            all agents, every project
  Register in current project  run from project root
  Pair extension for this project
  List configured projects
  Exit

Pair the extension

Choose Pair extension for this project from the menu (or run autoqai pair directly). If AutoQAI isn't registered with any client yet, it first offers to do that for you. It then starts the listener and prints the pairing details:

────────────────────────────────────────────────────────────
 AutoQAI — pairing details
 Project  checkout-web
 Port     7770
 Token    7K2Q9F

 Open the AutoQAI browser extension popover, choose this
 project, enter port 7770 and paste the token above.

 Paired ✓ — server running. Pair more tabs if you want.
 To use the AI features, stop this server and start your agent.
────────────────────────────────────────────────────────────

1. Click the AutoQAI icon in your browser toolbar to open the popover.
2. Choose Pair a project and enter the host 127.0.0.1, the port (7770 by default), and the pairing token shown in the terminal.
3. Click Pair & connect. The project now appears as paired.

Bind the tab to test

1. Open and sign into the page you want the agent to drive.
2. In the popover, pick the paired project and click Attach on the active tab.
3. Give the binding a short label (e.g. main or checkout) so the agent can target it.

Pairing and binding a tab in the extension popover

Pairing and binding a tab in the extension popover

Command-line tool

The autoqai command is both the MCP server your agent runs and a small toolkit for managing projects. Here's the full set of subcommands:

Run the server directly

Most agents start the server for you once registered. To run it yourself — for example to watch the logs — use serve:

# Run the MCP server directly (no menu)
autoqai serve

Need a non-default port or a custom display name?

# Choose a different port and a friendly name
autoqai serve --port 7780 --project-name "Checkout web"

Give the agent project context

Each project keeps a PROJECT.md file the agent reads before every run. Use it to describe what the app is, where key screens live, and any rules the agent should know. You can edit it directly or from the dashboard's Project section.

# Project context

This app is an internal billing dashboard.

- Log in is handled by corporate SSO — assume the tab is
  already authenticated.
- The primary navigation lives in the left rail.
- "Invoices" is the most important screen to keep healthy.
- Currency is always shown in EUR with a trailing symbol.

A few sentences of context dramatically improves the quality of test plans and findings — it's the difference between an agent guessing and an agent that knows your app.

Configuration

Project configuration lives in .autoqai/config.json, created on first run. It records the port, the pairing token, which capability groups are enabled, and any integrations. You can edit it by hand or from the dashboard's Settings and Integrations sections.

The Settings section of the dashboard

The Settings section of the dashboard

{
  "projectId": "checkout-web",
  "projectName": "Checkout web",
  "port": 7770,
  "pairingToken": "7K2Q9F",
  "enabledTools": {
    "interact": true,
    "assertions": true,
    "comparison": true,
    "screenshot": true,
    "evaluate": true
  },
  "integrations": {
    "jira": { "baseUrl": "https://your-company.atlassian.net" }
  }
}

Turning capabilities on and off

The enabledTools block lets you scope what the agent is allowed to do — for example, disable page interaction during a read-only audit, or turn off comparisons when you don't need them. Settings changes apply to the running server immediately.

Environment variables

Settings can also come from the environment. Command-line flags override environment variables, which override the config file.

# .env  (optional — flags and config override these)
AUTOQAI_PORT=7770
AUTOQAI_HOST=127.0.0.1
AUTOQAI_PROJECT_NAME=Checkout web
AUTOQAI_LOG_LEVEL=info

Run a testing task

With a tab bound, queue a testing task from the dashboard's New testing task section — a short description, optional element selectors picked straight from the page, screenshots, and any linked tickets. Then ask your agent to start working:

Test the Invoices screen end to end:
create a new invoice, verify it appears in the list with the
right total, then check the empty-state message after deleting it.

The agent picks up the task and, in order:

1. Drafts a plan of test cases you can see in the dashboard.
2. Drives the page through your signed-in session, case by case.
3. Runs assertions and records a finding for anything worth surfacing.
4. Captures screenshots, console output, and network activity as evidence.
5. Finalizes the run with an overall pass / fail summary.

A completed run with test cases and findings

A completed run with test cases and findings

Report and fix a bug

When you hit a bug, open the dashboard's Bug report section and capture it straight from the page — current URL, a screenshot, the DOM snapshot, the selected element, plus the console and network trails. Queue it, then point your agent at it:

Reproduce the bug I just queued. It's about the
date filter on Reports resetting when you paginate. Confirm it,
find the cause, and verify your fix in the browser.

The agent reproduces the issue in the browser, uses your editor tools to find and fix the cause, and then validates the fix live before recording a finding — so you get a confirmed bug and a verified fix in one pass.

Capturing a bug report from the page

Capturing a bug report from the page

Compare two versions

For redesigns and regression sweeps, bind two tabs — say staging and production — and ask the agent to compare a surface across them:

Compare the Invoices table on this staging tab
against the production tab I also bound. Flag any row, column,
or formatting differences.

AutoQAI extracts each side and diffs it offline and deterministically, so no tokens are spent reasoning over raw rows or chart points. It can compare:

• Data tables — including merged cells and per-cell formatting
• Forms — labels, values, types, required state, and help text
• Charts — by series and data point
• Metric cards and labelled-value sections
• Computed styles, property by property

Differences are recorded as findings and rendered as a precise visual diff in the dashboard.

Build & run regression test cases

One-off testing tasks are great for ad-hoc checks, but the work you repeat after every change belongs in a regression library. The dashboard's Test cases section lets you curate reusable cases, organised the way your product actually works, and saved as tracked files in your repo so they review and version like code.

How a library is organised

• Module. The top-level grouping — usually an area of your product, such as Checkout or Authentication. Each module gets its own folder on disk.
• Feature. A set of related cases within a module — for example "Sign in with email". Each feature is one tracked file inside the module folder.
• Test case. A single thing to verify, written in plain language, with an optional element selector picked from the live page.

Author cases — by hand or with AI

• Author by hand — add modules and features, type each case in plain language, and pick selectors straight from the bound tab instead of typing them.
• Generate with AI — describe the area to cover and let the agent draft a starter library from your project context, optionally letting it look at the live screen for accuracy.
• Refine anytime — edit, add, or remove cases; updates are written back to the same tracked files, so the library lives in your repo and reviews like code.

Queue a run

When you're ready to verify, switch the section into selection mode, pick what to run, and queue it — then point your agent at the queue:

Run the regression test cases I just queued for the
Checkout module. Walk each case in the browser, mark it
passed or failed, and record a finding for anything that breaks.

• Select any mix of whole modules, individual features, or single cases, then queue the selection as a run.
• Toggle Look at screen to let the agent capture page snapshots while it works through each case.
• The agent marks each case passed, failed, or skipped and records findings for anything that breaks.
• Results appear in the queue and history exactly like testing tasks and bug reports, grouped by case.

Because the library is stored under .autoqai/testcases and tracked in git, your whole team shares the same regression suite — and every run links its results back to the exact cases that produced them.

Selecting modules, features, and cases from the regression library

Selecting modules, features, and cases from the regression library

Jira integration

Point AutoQAI at your Jira instance and the agent can pull ticket details to test against the real acceptance criteria. Open the dashboard's Integrations section, enter your Jira base URL, and validate the connection.

• Requests are proxied through your own authenticated browser session — AutoQAI never sees or stores your Jira credentials.
• Once configured, the agent can fetch a ticket's description, status, assignee, comments, attachments, and linked issues.
• Link tickets to testing tasks and bug reports so the agent has the full context before it starts.

Privacy & security

AutoQAI is built to keep everything on your own machine.

• Loopback only. The server binds to 127.0.0.1 and refuses connections from any non-local address at connect time.
• Token-paired. The extension attaches only after you enter the one-time pairing token printed by the server.
• Your session stays yours. AutoQAI drives the tab you've already signed into; it never collects, stores, or transmits your credentials, cookies, or tokens.
• Local artifacts. Configuration, the project context, the task queue, and every run's test cases, steps, findings, and screenshots are written to the .autoqai folder in your project.
• No telemetry. There are no AutoQAI servers and no analytics — nothing phones home.

Troubleshooting

How-to & tips

Quick answers to the questions that come up most while getting set up.

FAQ