agent-qa-console 0.8.0

Visual browser QA console for AI coding agents — live browser, element selection, source mapping, RTL/a11y/perf audits, and test-fix-verify loops.

Agent QA Console

The visual browser QA console for AI coding agents

Let Claude Code, Cursor, Codex, Pi, or any MCP-aware agent open your app in a real browser, select UI elements visually, map them back to source files, fix code, and verify the result, while you watch.

Watch the agent. Pick any element. Map it to code. Fix it. Verify it.

Built by BrainboxAI: AI agent tooling, browser QA automation, and Hebrew/RTL-first product engineering.

---

Why developers star this

AI coding agents can generate code fast. The hard part is knowing whether the feature actually works in the browser.

Agent QA Console gives your agent a real browser and gives you a clean live view:

• 🖱️ Live agent browser: watch exactly what the agent sees.
• ✨ Animated assistant cursor: agent actions are visible, not mysterious.
• 🎯 Visual element selection: click any visible element and send it to the agent.
• 🧭 Source mapping: selected DOM element to its likely source file.
• 🧪 QA audits: RTL/Hebrew, a11y, perf, SEO, links, assets, forms, logs.
• 🔁 Test, fix, verify loop: the agent edits code with its normal tools, then retests.
• 🛡️ Human approval gates: pause before risky actions.
• 🧾 Clear logs and evidence: screenshots, browser logs, findings, and commands.

It is not another static report. It is a control plane for browser QA by AI agents.

---

60-second quickstart

Option A - install from PyPI

Use this once agent-qa-console is published on PyPI:

pipx install agent-qa-console
agent-qa-console setup all

If pipx says No matching distribution found, the package has not been published to PyPI yet. Use Option B or Option C below.

Option B - install from GitHub

pipx install git+https://github.com/brainboxai-il/agent-qa-console.git
agent-qa-console setup all

Option C - install from a local checkout

git clone https://github.com/brainboxai-il/agent-qa-console
cd agent-qa-console
pipx install .
agent-qa-console setup all --pi-source .

The setup all command installs the browser runtime and registers Agent QA Console with supported local agents: Claude Code, Codex, Gemini CLI, OpenCode, Cursor, and Pi when they are installed.

You can also target one agent:

agent-qa-console setup claude-code
agent-qa-console setup codex
agent-qa-console setup gemini
agent-qa-console setup opencode
agent-qa-console setup cursor
agent-qa-console setup pi

For an editable local development install that uses the legacy command name:

agent-qa-console setup all --command qa-mcp --pi-source .

Manual MCP registration

If you prefer to register manually:

claude mcp add qa agent-qa-console
codex mcp add qa -- agent-qa-console
gemini mcp add qa agent-qa-console

Cursor uses ~/.cursor/mcp.json; OpenCode uses ~/.config/opencode/opencode.json; Pi uses pi install with the companion Pi package.

Claude Desktop

{
  "mcpServers": {
    "qa": { "command": "agent-qa-console" }
  }
}

Cursor / Codex / Gemini / Pi

Use command:

agent-qa-console

Then ask your agent:

Open Agent QA Console for http://localhost:3000.
Test the page, let me select elements visually, map selected elements to code,
fix issues you find, and verify the result in the browser.

---

The killer workflow

1. Agent opens your app in a real browser
2. You watch the live page in Agent QA Console
3. You click any visible element in the page
4. The agent receives selector/text/data-source/bounding-box/url
5. Agent maps the element to a likely source file
6. Agent edits code using its normal file tools
7. Agent refreshes the browser and verifies the fix

Example selected element payload:

{
  "label": "Talk to us",
  "tag": "a",
  "className": "secondary-cta",
  "selector": "section.pricing-card > a.secondary-cta",
  "dataAttrs": {
    "data-agent-id": "pricing-cta",
    "data-source": "src/components/PricingCard.tsx"
  },
  "sourceHint": "src/components/PricingCard.tsx",
  "url": "http://localhost:3000/pricing"
}

Source mapping result:

{
  "matches": [
    {
      "file": "src/components/PricingCard.tsx",
      "matchType": "direct_source_hint",
      "confidence": 1.1
    }
  ]
}

For best results in your app, add lightweight hints:

<button
  data-agent-id="pricing-cta"
  data-source="src/components/PricingCard.tsx"
>
  Start
</button>

---

What it looks like in practice

Agent QA Console keeps the main screen minimal:

• the live browser view
• the assistant cursor
• selectable element overlays
• a small Logs drawer
• a selected-element action bar: Inspect, Explain, Fix

No giant dashboard. No noisy sidebars. Just the agent's browser.

---

Core tools

Browser control

• browser_open, browser_navigate, browser_get_state
• browser_click, browser_type, browser_hover, browser_scroll
• browser_screenshot, browser_logs, browser_close

Console control

• qa_console_open
• qa_console_pending_commands
• qa_console_ask_approval
• qa_console_status

Audits

• qa_rtl_audit: Hebrew/RTL QA, the unique differentiator
• qa_a11y_audit: axe-core accessibility scan
• qa_perf_metrics: Web Vitals
• qa_seo_check: SEO metadata and structure
• qa_scan_links: links and CTA risk
• qa_asset_audit: broken/blocked visual assets
• qa_conversion_audit: lead/sales blockers

Project context

• qa_project_context: filtered source tree, framework, routes, components
• qa_map_selected_element_to_source: visual selection mapped to a likely file/line

Advanced tools still exist for CI, reports, baselines, training data, design extraction, and integrations. The default catalog shows only the recommended core.

---

Hebrew/RTL is first-class

Generic QA tools miss Hebrew and RTL bugs. Agent QA Console catches:

1 + plural noun  wrong Hebrew plural agreement
"Get Started →"  wrong arrow direction in RTL flow
lang="he"        but missing dir="rtl"
English CTA       inside Hebrew UI
Hebrew + Latin    without bidi isolation
visual overflow   that appears only on mobile

Use it for Israeli SaaS, gov/public-service sites, e-commerce, dashboards, landing pages, and any Hebrew/Arabic RTL UI.

---

How it compares

Tool	Great at	Missing
Playwright / Selenium	Browser automation	Agent-native workflow, approval gates, source mapping
Lighthouse	Perf/SEO	Real flows, forms, source fixes, RTL
Percy / Chromatic	Visual diffs	Logic, logs, forms, agent repair
BrowserStack	Browser infrastructure	AI test-fix-verify loop
Autonomous QA bots	Reports	Human-supervised live browser repair
Agent QA Console	Agent browser QA + visual selection + source mapping + verification	Your coding agent still does code edits

---

CLI mode

You can run audits without an MCP client:

agent-qa-console audit https://example.com
agent-qa-console rtl https://example.co.il --json
agent-qa-console run qa.config.json

Minimal config:

{
  "name": "app-qa",
  "base_url": "http://localhost:3000",
  "browser": "chromium",
  "scenarios": [
    {
      "name": "homepage",
      "path": "/",
      "audits": ["a11y", "perf", "seo", "links"],
      "thresholds": {
        "a11y": { "max_critical": 0, "max_serious": 0 },
        "perf": { "min_score": 80 },
        "seo": { "max_issues": 2 }
      }
    }
  ]
}

Run:

agent-qa-console run qa.config.json

---

Safety model

Agent QA Console is defensive by design:

• No internal LLM. Your coding agent provides reasoning.
• Browser actions are deterministic and return structured JSON.
• Risky actions can go through approval gates.
• Sessions run locally by default.
• Passive security checks only: no exploitation, brute force, or port scanning.

Recommended agent rule:

Never submit real forms, delete data, create external issues, run payments, or make large source edits without explicit user approval.

---

Architecture

flowchart TD
    User[Human developer] <--> Agent[AI coding agent<br/>Claude Code / Cursor / Pi / Codex]
    Agent -->|MCP tool calls| AQC[Agent QA Console]
    AQC --> Browser[Real browser<br/>Playwright]
    Browser --> App[Your app / website]
    AQC --> UI[Live console<br/>browser · cursor · selection · logs]
    AQC --> Mapper[Project context<br/>source mapping]
    Mapper --> Code[Your codebase]
    Agent -->|normal file tools| Code
    Agent -->|retest after patch| AQC

---

Development

For local development, prefer an editable install:

git clone https://github.com/brainboxai-il/agent-qa-console
cd agent-qa-console
pip install -e ".[dev]"
python -m playwright install chromium
python -m pytest -q

Register the local development command with all supported agents:

agent-qa-console setup all --command qa-mcp --pi-source .

Or register one agent at a time:

agent-qa-console setup claude-code --command qa-mcp
agent-qa-console setup codex --command qa-mcp
agent-qa-console setup gemini --command qa-mcp
agent-qa-console setup opencode --command qa-mcp
agent-qa-console setup cursor --command qa-mcp
agent-qa-console setup pi --pi-source .

Quality checks:

python -m ruff check src tests
python -m mypy
python -m pytest -q --tb=short

Maintainer publishing checklist

Build and verify the package before publishing:

python -m pip install --upgrade build twine
rm -rf dist build src/*.egg-info
python -m build
python -m twine check dist/*

Publish to PyPI with an API token:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-...
python -m twine upload dist/*

PowerShell equivalent:

$env:TWINE_USERNAME="__token__"
$env:TWINE_PASSWORD="pypi-..."
python -m twine upload dist/*

After publishing, verify the public install path:

pipx install agent-qa-console
agent-qa-console setup all
agent-qa-console --help

PyPI versions are immutable: if 0.8.0 was uploaded once, publish fixes as 0.8.1, 0.8.2, etc.

---

Roadmap

• Smarter source mapping when apps do not include data-source.
• Better selected-element actions: inspect/explain/fix recipes.
• One-command demo project.
• GitHub Action templates for pre-deploy QA gates.
• More deterministic fix suggestions beyond RTL.
• Hosted/team session mode.

---

Contributing

Contributions are welcome. Good first issues:

• Improve source mapping heuristics.
• Add framework-specific route detection.
• Add more visual selection metadata.
• Reduce RTL false positives.
• Add examples for Claude Code, Cursor, Pi, Codex, and Gemini.

See CONTRIBUTING.md.

---

Built by BrainboxAI

Agent QA Console is built by BrainboxAI, a product studio focused on practical AI-agent systems, QA automation, and Hebrew/RTL-first software engineering.

We use it internally to make AI coding agents safer, more visible, and more reliable before code reaches users.

---

Star history

If this project helps you trust AI-generated code before shipping, please give it a star. It helps other developers find it.

---

License

MIT © BrainboxAI