QA Copilot · Documentation

The browser, readable by your agent

Install the extension, wire the MCP bridge into your coding agent, and let it read what actually happened in the tab — findings, selectors, failing responses — instead of your description of it.

Wire up the bridge Add to Chrome ↗

What Qiksy is

A manual-QA sidekick that lives in the browser you already test in — and hands everything it sees to your coding agent.

Qiksy watches the page while you use it: console and JavaScript errors, failed requests with the server’s actual error body, accessibility and markup problems, form submits that go nowhere. It fills forms with realistic data, keeps isolated logins side by side in one window, and turns a session into a paste-ready report.

The part that matters for developers is the bridge: an MCP server that exposes that live state to Claude Code, Cursor, Cline, Windsurf, Zed or VS Code. You say “fix what Qiksy found on this page” and the agent has the findings, the selectors and the failing responses — from the session you are already logged into.

The distinction worth keeping in mind: Qiksy never launches, switches or steals focus from a browser. It works inside your existing tab — including a background one — which is what separates it from a driver that pops a fresh window every run.

What it does not do

By default it senses and reports; it does not click, type, submit or navigate the app under test. That boundary is deliberate — it is what makes a tool that watches other people’s applications trustworthy. Agent control is the knowing exception, off until you turn it on (see Agent control).

Installing the extension

1Install from the Chrome Web Store.
2Pin it to the toolbar — you will open the panel often.
3Open the site you are testing. The toolbar icon opens the popup — settings, the per-site switch, the licence and the bridge toggle. The working panel is opened from the page itself: the round Q button Qiksy injects, or Alt+Shift+Q.

Nothing to configure, no account, no key. The free tier is usable on its own — the panel, audits, form filling and isolated logins all work without a licence. The session report and the MCP bridge are Pro (see Plans).

Permissions, and why each exists

Permission	Why
Access to the sites you visit (`<all_urls>`)	Qiksy has to work on whatever you are testing — a staging host nobody can enumerate in advance. The per-site switch in the popup decides where it actually runs.
`scripting`	Injects the panel and reads the DOM: selectors, form fields, ARIA state.
`webRequest`	A failed request is only useful with its status and response body — the difference between “something broke” and “the API says the token expired”.
`cookies`	Isolated logins only. Keeping several sessions apart means intercepting the site’s cookies, session cookies included. This one is serious enough that the extension asks for its own explicit confirmation the first time, naming exactly what it touches — it is never silently on.
`declarativeNetRequest`	Keeps each isolated login’s requests carrying its own identity instead of the browser’s shared one.
`storage`, `unlimitedStorage`	Your settings, the licence and the current session’s findings — locally.
`contextMenus`, `alarms`	The right-click entry points and the timers behind licence checks and session upkeep.

Qiksy reads what the tab shows you and keeps it local. It is not a telemetry product — findings leave your machine only when you export them, or when your own agent asks for them over the local bridge.

The panel

Everything Qiksy noticed on this page, ranked, each with the selector you need to act on it.

Audit

One pass over the live page: console errors, uncaught exceptions, failed and slow requests, accessibility problems, markup that will bite (duplicate ids, labels pointing nowhere, inputs with no name), and forms whose submit does not go anywhere.

Every finding carries a severity, a CSS selector and the detail behind it. Selectors are the whole point — a finding you cannot locate is trivia.

Smart form fill

Qiksy reads the form — types, labels, patterns, required flags — and fills it with data that is plausible rather than random, so validation behaves the way it will for a real user. Fill one field or the whole form; custom widgets and multi-step flows are handled field by field.

Isolated logins

Open the same application as several users in one window, each tab with its own cookies, localStorage, IndexedDB and Cache Storage. Admin next to customer, seller next to buyer — no incognito windows, no separate browser profiles, no logging out.

Isolation is about identity, not focus. Sessions stay independent in the background; a browser only ever renders one tab actively, so an agent drives one at a time.

Exploratory tour

A checklist generated from what the page actually contains — the flows worth trying here, not a generic list. Useful when you inherit a feature and have no idea where the soft spots are.

Report

The session as something a human can read and a ticket can hold: what was tested, what broke, the repro steps, the selectors, the failing responses. Paste-ready.

The MCP bridge

Switch the bridge on in the extension, paste one block into your agent’s config. No clone, no local path, no version to pin.

agent  ⟷ (MCP over stdio)  ⟷  qiksy-mcp  ⟷ (WebSocket @ 127.0.0.1)  ⟷  extension

The extension is the WebSocket client — a service worker cannot listen on a socket — and the bridge is the server, bound to loopback only. Nothing is reachable from outside your machine.

First: switch the bridge on in the extension

The extension side is off until you turn it on, and the two halves authenticate to each other with a shared token. Do this before touching your agent’s config, or the bridge will sit silent with nothing to explain why.

1Open the toolbar popup → Agent bridge · MCP and switch it On.
2Accept the one-time consent prompt. Until you do, the bridge reports blocked and refuses to connect.
3Press Generate to mint a token, then 📋 Copy agent config — that gives you the exact block for your editor, token and port already filled in.

The status line under the toggle (🟢 / 🟡 / 🔴) is the first place to look when something does not connect: off, connecting, waiting, rejected, lapsed, blocked, replaced.

Claude Code

claude mcp add --transport stdio qiksy \
  --env QIKSY_MCP_TOKEN=YOUR_TOKEN \
  -- npx qiksy-mcp --port 7333

Claude Desktop, Cursor, Windsurf

{ "mcpServers": { "qiksy": {
  "command": "npx",
  "args": ["qiksy-mcp", "--port", "7333"],
  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
} } }

Zed

{ "context_servers": { "qiksy": {
  "source": "custom",
  "command": "npx",
  "args": ["qiksy-mcp", "--port", "7333"],
  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
} } }

VS Code

{ "servers": { "qiksy": {
  "type": "stdio",
  "command": "npx",
  "args": ["qiksy-mcp", "--port", "7333"],
  "env": { "QIKSY_MCP_TOKEN": "YOUR_TOKEN" }
} } }

The token is not optional. Without QIKSY_MCP_TOKEN the bridge closes every connection with auth failed before any data moves, and the extension will not dial out either — you get silence, not an error naming the cause. Use the same value the popup generated, and the same port on both sides.

The package is qiksy-mcp on npm, versioned in lockstep with the extension. npx always fetches the current build, so there is no version to keep in step by hand. Node 18 or newer.

The bridge as a whole is a Pro surface. The extension’s free tier stays fully usable, but the socket refuses to connect without a valid licence or an active trial — when a trial lapses, every tool fails with a message saying so, qa_export included. Do not design a free-tier integration around the read-only tools.

Checking it works

Open a page with the extension active, then ask the agent to call qa_status. You should get the URL and the current error, warning and form counts. If it reports no connection, see Troubleshooting.

Tool reference

Eighteen tools. Every one accepts an optional tabId (from qa_tabs); without it they act on the active tab.

Reading the page

Tool	What it returns
`qa_tabs`	Every tab Qiksy can read, including which are isolated logins (`isolatedSession` = the login name). The `tabId` you pass to everything else comes from here.
`qa_status`	URL, error / warning / form counts, and the isolated-login name if any.
`qa_findings`	Findings with selectors and detail. `severity` = `all` \| `error` \| `warning`.
`qa_snapshot`	Whole-page accessibility snapshot with stable `ref` handles — the map an agent needs before acting.
`qa_export`	The full `qa-export/v1` bundle: findings, forms, network, repro steps.
`qa_tour`	The exploratory checklist for this page.
`qa_report`	Generates the session report; `spec` shapes what goes in.

Driving Qiksy’s own surfaces

Tool	What it does
`qa_open_panel`	Opens or closes the panel, optionally on a given tab of it.
`qa_run_audit`	Re-runs the audit on the page as it is right now.
`qa_spotlight`	Highlights an element in the page by `selector` or `ref` — the fastest way for an agent to show you what it means.
`qa_wait_ready`	Waits for the page to settle before the next step.

Agent control (Pro, opt-in)

Tool	What it does
`qa_click`	Clicks an element by `selector` or `ref`.
`qa_type`	Types `value` into a field.
`qa_type_many`	Fills a whole form in one call. `fields` is a list of `{selector, value}` pairs — this tool takes selectors only, no `ref`, unlike every other acting tool.
`qa_press`	Sends a key, optionally to a specific element.
`qa_navigate`	Navigates the tab — within the site under test only. A hop to another domain (an external SSO, a payment provider, a docs link) is refused as `out-of-scope`.
`qa_open_isolated`	Opens a URL as a fresh isolated login — same-site only, and behind a separate consent of its own (see Agent control).
`qa_close_tab`	Closes a tab it opened.

Targets are a selector or a ref from qa_snapshot. Prefer ref: it survives the re-render that invalidates a hand-written selector, which is the usual reason a scripted step fails on the second run.

Agent control

Letting the agent act inside the session you are already logged into — off by default, and deliberately hard to enable by accident.

Everything above senses. Agent control acts: click, type, fill a form, press a key, navigate, open an isolated login. It exists because the valuable session is the one you are already authenticated in — the state a cold automated browser cannot reach without you handing it credentials.

Turning it on

1Requires Pro.
2Open the panel → Tools → Agent control. It is a card there, not a setting in the popup — off on a fresh install and off until you turn it on.
3Confirm the prompt it shows. It names what you are enabling; it is not a checkbox you can pass over.

Opening an isolated login (qa_open_isolated) needs a third confirmation that Agent control does not cover. Multi-login intercepts the site’s cookies, session cookies included, so it asks separately. With Pro and Agent control both on, that call still refuses until you accept it.

The rules it operates under

It acts on one active tab at a time. Isolated logins keep separate identities, but a browser renders one tab actively, so parallel driving of several sessions is not offered — the honest limit, stated rather than worked around.
It never opens arbitrary HTML or evaluates code you did not ship. Actions come from a closed vocabulary — the tools above and nothing else.
It is scoped to the tab you point it at. There is no “go find the page” mode.

Use it on applications you are authorised to test. It acts with your session’s privileges — an agent clicking “delete” in an admin panel deletes exactly as you would.

A working session

What this looks like in practice, from opening a page to a fix in the editor.

1Open the feature you are testing and use it like a person would. Qiksy watches while you do.
2Open the panel. Run the audit. What broke is already listed with its selector.
3Fill the form with smart fill instead of typing test data by hand — validation then behaves like it will for a real user.
4Ask your agent: “read what Qiksy found on this tab and fix it.” It calls qa_findings, gets the selectors and the failing responses, and works from the real state instead of your description of it.
5Generate the report for the ticket — repro steps, findings and responses, paste-ready.

Prompts that work well

Read the Qiksy findings on the active tab and fix the errors in this repo.

Take a qa_snapshot, then fill the checkout form with valid data and tell me
what validation fires.

Compare qa_status across my isolated logins — does the admin see something
the customer should not?

The pattern that pays off: let the agent read the browser state rather than describing it yourself. Everything you would have paraphrased — the exact error, the selector, the response body — it can fetch precisely.

Free and Pro

	Free	Pro
Panel, audits, findings with selectors	Yes	Yes
Smart form fill	Yes	Yes
Isolated logins	Yes	Yes
Export (`qa-export/v1` bundle)	Yes	Yes
Session report (History tab)	—	Yes
MCP bridge (all eighteen tools)	—	Yes
Agent control	—	Yes, opt-in

Pro is $49 for a year, one payment — no stored card, no automatic renewal. Every new install gets a 14-day trial of Pro; when it lapses the extension keeps working, the bridge stops.

The licence is an offline key: it validates on your machine without calling home. Losing your network does not lose your Pro.

Troubleshooting

The agent says the tool is unavailable

Check the extension is installed and the tab is open — the bridge talks to a running extension, not to a service.
Check your licence or trial. The socket refuses to connect without one, and every tool fails the same way when it does.
Restart the MCP client after adding the server; most only read their configuration at startup.

Findings look empty on a page that is clearly broken

Errors are collected as they happen. If the extension was installed or the panel opened after the failure, reload the page and reproduce — then it is captured with its request and response.

A selector that worked once now fails

The page re-rendered. Take a fresh qa_snapshot and target by ref instead — refs are handles into the current snapshot rather than guesses about the markup.

Nothing happens on chrome:// pages

Chrome does not let any extension read its own internal pages, the Web Store, or another extension’s pages. That is a browser rule, not a Qiksy limitation.