Metadata-Version: 2.4
Name: agent-qa-console
Version: 0.8.1
Summary: Visual browser QA console for AI coding agents — live browser, element selection, source mapping, RTL/a11y/perf audits, and test-fix-verify loops.
Author-email: BrainboxAI <hello@brainboxai.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Brainboxai-IL/agent-qa-console
Project-URL: Issues, https://github.com/Brainboxai-IL/agent-qa-console/issues
Project-URL: Repository, https://github.com/Brainboxai-IL/agent-qa-console
Keywords: agent-qa-console,mcp,ai-agents,coding-agents,browser-automation,qa,testing,playwright,source-mapping,rtl,hebrew,a11y,axe-core,web-vitals,visual-regression
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: playwright>=1.45.0
Requires-Dist: pydantic>=2.0
Requires-Dist: Pillow>=10.0
Requires-Dist: questionary>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

<div align="center">

# 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.

[![PyPI](https://img.shields.io/pypi/v/agent-qa-console.svg)](https://pypi.org/project/agent-qa-console/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io)
[![Playwright](https://img.shields.io/badge/browser-Playwright-2ea44f)](https://playwright.dev/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**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.

</div>

---

## 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)

```bash
pipx install agent-qa-console
agent-qa-console init
```

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

### Option B - install from GitHub

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

### Option C - install from a local checkout

```bash
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:

```bash
agent-qa-console setup all
```

You can also target one agent:

```bash
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:

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

### Manual MCP registration

If you prefer to register manually:

```bash
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

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

### Cursor / Codex / Gemini / Pi

Use command:

```text
agent-qa-console
```

Then ask your agent:

```text
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

```text
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:

```json
{
  "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:

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

For best results in your app, add lightweight hints:

```tsx
<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:

```text
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:

```bash
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:

```json
{
  "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:

```bash
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

```mermaid
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:

```bash
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:

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

Or register one agent at a time:

```bash
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:

```bash
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:

```bash
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:

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

PowerShell equivalent:

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

After publishing, verify the public install path:

```bash
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`](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
