agent-qa-console

---

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 (recommended)

pipx install agent-qa-console
agent-qa-console init

PyPI: https://pypi.org/project/agent-qa-console/

Option B - install from GitHub

pipx install git+https://github.com/Brainboxai-IL/agent-qa-console.git
agent-qa-console init

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 init --pi-source .

The init wizard 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.

For non-interactive setup/CI, use:

agent-qa-console setup all

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

---

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 init
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