🦊 Fagun

Give any AI a browser to use your product like real customers, run full UAT, hunt real bugs, and tell you if it's ready to ship.

Fagun is a single tool that plugs into Claude, Cursor, Codex, Antigravity, Windsurf, Cline, or VS Code. Once it's set up, you just type fagun (or /fagun) and your AI can open a real browser and:

• Use the site as real end users — mobile, slow-internet, low-end, keyboard-only, screen-reader, international, first-time visitor — with real device + network emulation.
• Understand the business first — map the target's CTAs, forms, navigation, auth state, and likely revenue/conversion flows before judging it.
• Run User Acceptance Testing — walk complete journeys (signup, login, search, checkout, password reset…) step by step and confirm a real user can finish them.
• Fuzz every input field — valid, invalid, negative, empty, whitespace, special-character, unicode, boundary, and injection-observation cases.
• Hunt real, reproducible bugs — broken links, console/JS errors, failed requests, form-validation gaps, accessibility violations, slow pages, security misconfig.
• Deliver a product-readiness verdict — a 16-category scorecard (UX, UI, business logic, a11y, perf, security…) and a release decision, with prioritized fixes.

You set it up once. It works in every AI tool. Chrome installs itself.

🌐 Website: https://mejbaurbahar.github.io/fagun/ · 📦 PyPI: https://pypi.org/project/fagun/

No model API key required

Fagun does not require users to bring a Groq, OpenAI, Anthropic, Gemini, or other model API key. It runs inside the AI app the user already chose. Claude, Codex, Antigravity, Cursor, Windsurf, or a local MCP-capable model does the reasoning; Fagun supplies the browser, QA, security, evidence, and report tools.

For plain-English browser tests, ask your AI:

fagun https://example.com: search for "pricing" and verify results load

The AI should call autoqa_prompt(url, goal), create a small plan with its own model, then execute it with Fagun tools like navigate, click, fill, screenshot, get_console, and get_network. Fagun should open Chrome through Chrome DevTools MCP automatically when the AI client exposes it, using the user's default Chrome session. It should only fall back to Fagun's browser if Chrome MCP is unavailable or attach fails, and the fallback should be shown in the report. Fagun remains the main tool and report brand, but it should call installed supporting MCPs when useful. Jam MCP should be used when available for each important Interactive Test Flow step and for reproducible bugs, attaching a screenshot or screen recording with console/network context. At the end it should call autoqa_write_html_report to create a branded HTML report under ./reports/, then open the returned Report URL with Chrome DevTools MCP/default Chrome. The report includes project name, collected target URL, opened website logo, full prompt, Fagun Tools title, Interactive Test Flow steps, per-step evidence, Jam links/recordings, bugs, and fixes.

Supporting MCPs are routed by job:

• chrome-devtools: real/default Chrome session, logged-in testing, DevTools console/network/performance, report opening.
• jam: per-step screenshots/screen recordings and visual bug evidence.
• playwright: isolated/headless regression runs, multi-context checks, downloads/uploads, PDF/export checks, stable screenshots, trace/video-style automation.
• mcp-fetch: static page/API/header/robots/sitemap fetching without changing browser state.
• context7: current framework/library docs before fix advice that depends on library behavior.
• virustotal and shodan: optional authorized security intelligence when API keys are configured.
• LangGraph or similar host-side orchestration: useful for durable state, branching, retries, reviewer loops, or multi-agent test plans. Fagun remains the execution/reporting layer.

Phased power workflow:

• Phase 1 — Run Memory: autoqa_write_html_report stores structured JSON run records under reports/runs/; inspect them with autoqa_list_runs(limit).
• Phase 2 — Replay / Regression: autoqa_replay_prompt(run_ref) turns any stored run into a replay prompt for regression testing.
• Phase 3 — Report Comparison: autoqa_compare_runs(before_ref, after_ref) shows fixed, still-open, and new findings.
• Phase 4 — Power Modes: start with autoqa_power_plan(url, goal), then use evidence timeline fields, list_test_data, a11y_audit + keyboard_walk, map_api, deep_test(include_api_map=true), auth/session tools, and optional LangGraph orchestration.

Issue-tracker export is intentionally not included in this workflow.

⚡ One command sets up everything

Recommended, no Python needed:

uvx fagun init

Already installed but still seeing old output? Force the newest release:

uvx --upgrade --reinstall fagun init

If you prefer pip/Python:

pip install --upgrade fagun
fagun init

That's the whole install. fagun init installs the Chrome engine and auto-detects every AI tool on your machine (Claude Code, Claude Desktop, Cursor, Codex, Windsurf) and registers the fagun browser tools, Chrome DevTools MCP, + the /fagun skill in each one. It also opens chrome://inspect/#remote-debugging so Chrome can show the official Allow remote debugging? popup when Fagun attaches to your signed-in default Chrome session.

The setup output is a modern CLI dashboard: task, progress table, configuration files, final summary, and next commands. Paths are shortened with ~ so users can see exactly what changed without reading noisy logs.

If your terminal still says Fagun init — setting up everything…, you are running an old cached package. Refresh it with uvx --upgrade --reinstall fagun init or pip install --upgrade fagun && fagun init.

Then restart your AI tool and type fagun — followed by what you want tested.

After setup, use Fagun inside your AI tool:

fagun deep test https://example.com
fagun security scan https://example.com
fagun check links on https://example.com
fagun test the signup form on https://example.com

Paste-prompt (let the AI do it):

Install and set up fagun for me: install uv if missing, then run uvx fagun init. Follow https://github.com/mejbaurbahar/fagun/blob/main/install.md if anything fails.

Claude Code plugin:

/plugin marketplace add mejbaurbahar/fagun
/plugin install fagun@fagun

Target one tool:

uvx fagun install claude-code   # or: cursor | claude | vscode

macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" Then restart your terminal.

🚀 Manual install (any OS — no Python or pip needed)

Step 1 — install uv (it brings its own Python, so nothing else is required):

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

⚠️ Restart your terminal after this so uv is on your PATH. (macOS/Linux: or run source $HOME/.local/bin/env in the current shell.)

Step 2 — set up Fagun:

uvx fagun init       # installs browser + wires AI tools + Chrome DevTools MCP + /fagun skill

That's it. Restart your AI tool, type fagun, and go.

Already have pip/Python? Run pip install --upgrade fagun && fagun init.

💡 Don't want to think about config? Just tell your AI: "Install and set up fagun for me — follow https://github.com/mejbaurbahar/fagun/blob/main/install.md" and it does everything above for you.

🔌 Connect it to your AI tool

Every tool gets two MCP servers:

• fagun — UAT, bug hunting, security, a11y, forms, reports.
• chrome-devtools — official Chrome DevTools MCP for live DevTools debugging, console/network inspection, DOM/CSS inspection, and performance traces.

uvx fagun init writes both automatically. Manual config:

// Claude Desktop / Cursor / Windsurf / Cline / Antigravity
{
  "mcpServers": {
    "fagun": { "command": "uvx", "args": ["fagun"] },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--auto-connect", "--no-usage-statistics"],
      "env": {
        "CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS": "1",
        "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"
      }
    }
  }
}

# Codex — ~/.codex/config.toml
[mcp_servers.fagun]
command = "uvx"
args = ["fagun"]

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest", "--auto-connect", "--no-usage-statistics"]
env = { CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = "1", CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS = "1" }
startup_timeout_ms = 20_000

The -y flag prevents npx from asking the user to confirm package download. --auto-connect makes Chrome DevTools MCP attach to the user's running Chrome. On first setup, Fagun opens chrome://inspect/#remote-debugging; turn on remote debugging there, then click Allow when Chrome shows the permission popup. Users do not need to run fagun connect to my Chrome first; fagun deep test <url> should auto-use Chrome DevTools MCP when the AI client exposes it. If the target is still logged out, Fagun checks auth_status: the user can log in manually in Chrome, or provide authorized test credentials for login_with_credentials. Passwords are masked in output and the resulting session can be saved for future authenticated tests. Fagun opts out of Chrome DevTools MCP usage statistics and update-check noise in generated configs.

Restart the tool after adding it. Then type fagun.

🎬 See it in action

▶️ Live animated demo (macOS / Windows / Linux): https://mejbaurbahar.github.io/fagun/#see-it-in-action

Setup + first bug on each OS:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh   # get uv (once)
uvx fagun init                                     # browser + all AI tools + skill
# then, inside your AI tool, type:
#   fagun deep test https://example.com

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # get uv (once)
uvx fagun init                                     # browser + all AI tools + skill
# then, inside your AI tool, type:
#   fagun audit https://example.com

That's the whole flow: install uv → uvx fagun init → type fagun <task> in any AI tool.

💬 How to use it

Just talk to your AI in plain English:

• fagun → shows the menu and starts up
• go to example.com and take a screenshot
• run QA on https://example.com
• deep test https://example.com and save the report to ./report.md
• check for broken links on https://example.com
• test the forms on the signup page
• are there any console errors? · any failed network requests?
• log in with [email protected] / password123, then check the dashboard

🕵️ The /fagun bug hunter

Fagun ships with a skill that turns your AI into a methodical QA tester. It sweeps the full product-readiness surface and only reports bugs it can actually reproduce (no guessing):

Every finding comes with steps to reproduce, what was observed, and the impact.

🪙 Token-saving (on by default)

Browser tools normally flood your AI's context with huge JSON blobs and full network/console dumps — burning tokens fast. Fagun is built to be token-lean:

• Terse output by default — compact one-line-per-finding text instead of pretty JSON (~70% fewer tokens per result). Set FAGUN_TERSE=0 for full JSON, or pass verbose=true to any tool for one call.
• One call, not ten — deep_test crawls + checks console, network, forms, headers, a11y, perf across the whole site in a single tool call, instead of many manual navigate + get_console + get_network round-trips.
• Capped & deduped — long link/console/network lists are truncated with a +N more marker; duplicate findings are collapsed.
• Reports go to disk, not context — pass report_path and raw detail is written there; the final chat answer still shows the full user-facing result: verdict, all findings, evidence, fixes, coverage, and report link.

💡 Cheapest workflow: deep test <url> and save the report to ./report.md → one call, full Fagun answer in chat, raw evidence/report on disk.

⚙️ Options (optional)

Set these as environment variables if you need them:

For the lowest-token workflow, use:

FAGUN_TERSE=mini

Then ask: deep test <url> and save the report to ./fagun-report.html. The chat gets a tiny summary; the full evidence stays in the report file.

🎨 Fagun Style (same output across models)

Fagun ships a reusable response contract so Claude, Codex, Cursor, Gemini, Qwen, DeepSeek, or a custom wrapper can show results in the same style:

• fagun_style_prompt — copy into system/custom instructions for Markdown output.
• fagun_style_prompt(mode="json") — tells the model to return structured JSON.
• fagun_style_schema — JSON schema for a frontend renderer with cards/panels.
• fagun_render_response — converts JSON or plain text into Fagun-style Markdown.

Default sections: Executive Summary, Problem, Analysis, Solution, Implementation, Test Cases, Edge Cases, Risks, Production Impact, API Validation, Performance, Jira Ticket, and Final Recommendation.

🧠 Advanced security prompt + tool catalog

For deeper authorized bug-hunting workflows, Fagun now includes an AI security engineer prompt and an external-tool catalog. It does not blindly run exploit tools; it plans adapters, explains when each tool fits, and keeps execution scope-gated:

• fagun_security_prompt — improved enterprise prompt for authorized security testing.
• list_external_security_tools — catalog for Loxs, Skill Security Scanner, Shannon, Lonkero, recon-skills, payload corpora, RFC822 Email Validator, LostFuzzer, img-payloads, customBsqli, BeeXSS, TimeVault, and NextSploit.
• recommend_security_tools — picks the smallest relevant tool plan from the target profile and goal, then tells the AI how to validate and report evidence.

Use it for attack-graph planning, tool selection, deduplication, validation, remediation, and regression tests. Active probes still require authorization.

recon-skills is treated as a read-only methodology pack first: Fagun can use it to pick relevant recon, red-team, sector, chain, SAML, Docker, WordPress, CORS, XMLRPC, JS-secret, metrics, and API-flow checklists, then translate those into authorized Fagun-safe test plans.

🔐 Security scanning (authorized targets only)

security scan <url> runs the bug classes hunters get paid for — non-destructive, GET/HEAD only, no attacks on third parties:

• Exposed files (/.git, /.env, /.aws/credentials, backups, actuator)
• Leaked secrets in HTML/JS (AWS, Stripe, Google, GitHub, JWT, private keys)
• CORS misconfiguration · reflected-XSS candidates · open redirect · SQLi error signals
• Cookie flags · security headers (CSP/HSTS/X-Frame)

⚠️ Only scan sites you own or are authorized to test.

🔌 Use your own logged-in Chrome (self-healing + sessions)

• Chrome DevTools MCP uses --auto-connect during normal deep tests, so it can reuse your already-signed-in default Chrome after you allow remote debugging. Great for testing behind a login without giving credentials to the AI.
• If Chrome is not logged in, Fagun reports login-required and asks for manual login or authorized test credentials. login_with_credentials records the login action trace but prints the password only as [hidden].
• connect to my Chrome is only a troubleshooting fallback that launches a dedicated debuggable Chrome profile and attaches to it.
• browser_exec → when no built-in tool fits, the AI writes Python against the live page (full Playwright). save_helper persists what works, so Fagun gets smarter every run.

🧰 Everything it can do (MCP tools)

fagun_start · product_map · auth_status · login_with_credentials · open_browser · navigate · click · fill · press_key · screenshot · evaluate_js · get_console · get_network · crawl · run_qa · check_links · test_forms · fuzz_forms · list_test_data · perf_audit · a11y_audit · security_headers · security_scan · advanced_security · deep_test · full_qa_sweep · write_report · browser_exec · save_helper · list_helpers · load_helper · connect_chrome · fagun_security_prompt · list_external_security_tools · recommend_security_tools · close_browser

What's new in v0.7.0 — deeper, smarter, evidence-backed:

• fuzz_forms — actively fills every form field with a labelled test-data catalog (valid / invalid / negative / empty / whitespace / special character / unicode / boundary / out-of-box / injection) and reads the browser's real Constraint-Validation verdict. Reports include a field-by-field scenario matrix and screenshots for failed cases. A validation gap is reported only when the browser itself accepted a value it should have rejected.
• perf_audit — real Core Web Vitals (LCP, CLS, TBT, FCP, TTFB) from the browser's Performance APIs + a Lighthouse-comparable 0-100 score. No estimates.
• a11y_audit — deep WCAG 2.1 checks incl. real computed color-contrast.
• advanced_security / bigger security_scan — CSP quality, clickjacking, risky HTTP methods, mixed content, missing SRI, sensitive-page caching, host- header injection, CRLF, path-traversal/LFI, SSTI, command-injection, GraphQL introspection, error/stack-trace disclosure, sensitive-data-in-URL.
• Jira bug reports — every confirmed finding in Markdown/HTML reports gets a Jira-ready ticket: summary, priority, severity, steps, observed, expected, impact, evidence, screenshot path, and suggested fix.
• Every finding carries evidence — nothing is fabricated; unreproducible = not reported.

🛠️ For developers

git clone https://github.com/mejbaurbahar/fagun && cd fagun
pip install -e .
python -m playwright install chromium
python -m fagun        # runs the MCP server on stdio

Release (maintainer): publishing is automatic via GitHub Actions + PyPI Trusted Publishing. Bump the version in pyproject.toml and src/fagun/__init__.py, then:

git tag v0.3.0 && git push origin v0.3.0

MIT © Mejbaur Bahar Fagun