Argus

Point your coding agent at a web app. It explores like a QA tester and reports the bugs it can prove.

Argus is an MCP server. When Claude Code (or any MCP host) loads it, the agent stops being "an assistant with browser tools" and starts behaving like a senior tester — hypothesizing, clicking, verifying persistence, and recording reproducible bugs. Every certified finding is independently re-confirmed from a clean page load before it's reported.

Quick start · Why Argus · Compared · Tools · Benchmarks

The output

Give it a URL; get a self-contained report of bugs — each tagged with whether Argus independently reproduced it or only observed it:

The green badge is the whole point. Anyone can have an LLM claim a bug. Argus re-loads the page from scratch and re-checks the symptom before it says VERIFIED — so the report is a list of bugs you can trust, not a list of guesses to triage.

Related MCP server: Aiqaramba

How it works

flowchart LR
    A(["observe"]) --> B{"looks wrong?"}
    B -->|not sure| C["act: click · type · resize · verify"]
    C --> A
    B -->|bug| D["verify_persistence — reload from a clean state"]
    D -->|symptom repeats| E(["VERIFIED"])
    D -->|symptom gone| F(["dropped — no false positive"])
    E --> G[["report: HTML · JSON · JUnit · SARIF"]]

The agent is the intelligence. Argus is the seat you put it in: a role-binding prompt that keeps it in tester mode, a description-keyed tool surface (click_what("Login button"), not click(7)), and a reproduction-receipt engine that turns "the model thinks this is a bug" into "this bug is real, here's the proof."

Quick start

pip install argus-testing
playwright install chromium

# Wire it into Claude Code (or Cursor, or any MCP host)
claude mcp add argus -- argus-mcp

Then just ask, in your agent session:

"Test my app at http://localhost:3000 — find real bugs."

That's it. The agent drives; Argus keeps it honest and writes the report.

# Uses a LiteLLM-backed planner. Set a provider key (OPENAI_API_KEY, DEEPSEEK_API_KEY, …).
argus http://localhost:3000 --model deepseek/deepseek-chat

# Higher recall: union N independent passes (deduped, proven instance kept)
argus http://localhost:3000 --passes 3

pip install 'argus-testing[mac]'
brew install cliclick          # keystroke / coordinate fallback
argus-mcp --doctor             # check Screen Recording + Accessibility grants

Same description-keyed tools, but the target is whatever app is foreground on macOS — Notes, Cursor, Safari, your in-progress feature. No headless Chrome, no scripted Playwright. Argus sees what you see, via the Accessibility tree.

Why Argus is different

Existing testing tools only test what you script. Playwright and Cypress run the assertions you wrote. Argus discovers bugs you didn't think to test for — and then does the thing an LLM alone can't be trusted to do: proves them.

How it compares

On the axis that matters for finding bugs — autonomously discover, independently verify, and report — Argus occupies a different slot from the browser-MCP crowd:

These aren't "worse" tools — they're a different job. Playwright MCP gives an agent excellent hands; Chrome DevTools MCP gives it deep network/perf/memory inspection Argus doesn't have. Argus is the layer that decides what's a bug and proves it. Use them together.

Benchmarks

$ python -m argus.bench --target all

  buggytasks    22 / 22  = 100 %   ·  mechanical bugs (console errors, fake delete, auth bypass…)
  darkshop      12 / 12  = 100 %   ·  human-eye bugs (fake scarcity, lying toasts, stale state…)
  ──────────────────────────────────────────────────────────────────────
  total         34 / 34  = 100 %   ·  reproducible from git clone in two commands

34 / 34 is the capability ceiling — what's findable through the tool surface, measured by deterministic scripts. It is deliberately separate from how often a given LLM remembers to use the tools well, which is noisy and honestly reported below.

python -m argus.bench.agent_runner puts an actual model in the driver's seat and scores recall across trials. What we've learned running it:

1. Real recall sits well below the 34/34 ceiling. A live driver finds a fraction of the seeded bugs per pass — the ceiling is what's findable, this is what a model finds.

2. Variance is large — never rank models on a few runs. Per-trial recall swings widely; we report the spread, not a single hero number.

3. Dogfooding the bench found real bugs in Argus itself — a record_bug crash on a string argument that silently dropped findings, resolver misses on common phrasings. The tool-testing tool got tested.

4. Precision holds regardless of driver. Across every trial, the reproduction receipt kept false-certifications at zero — a weak model finds fewer bugs, but the ones marked VERIFIED are still real.

BuggyTasks (:5555) — 22 mechanical bugs in a task app: console errors, dead links, fake delete (UI says "deleted!" but data persists on refresh), auth bypass, NaN dates, off-by-one counts, race conditions. The "scripted E2E could find these" tier.

DarkShop (:5556) — 12 human-eye bugs in a polished-looking store: hardcoded "Only 3 left!" scarcity, -50% badges where sale price equals original, a "free shipping over $50" banner contradicted by a flat $5 at checkout, inverted visual hierarchy ("Add to Cart" demoted under a prominent "Subscribe"), cross-page state drift (rename sticks on /account, navbar greeting doesn't). Static analysis catches roughly none of these — they require an agent that reads the page and reasons.

python test-site/app.py           # BuggyTasks  :5555
python human-eye-fixture/app.py   # DarkShop    :5556
python -m argus.bench --target all

Tool surface

Safety: per-call timeout, a 30-minute session cap, a ~/.argus/abort panic file that halts every subsequent action, and an automatic before/after screenshot trail on every action.

Philosophy

Argus assumes an Opus-class driver. Static rules that pretend to be the smart layer are subtractive — they add maintenance and false positives and pull attention from what the agent actually saw. So detector.py is tiny: it only captures the two channels the agent literally cannot see (the console event stream and the HTTP layer). "Is this toast misleading? Is the visual hierarchy wrong? Is that count off?" — the agent reads observe() and decides.

The instructions block doesn't tell the agent to fire every XSS payload from a textbook. It defines a senior-tester worldview (Map → Hypothesize → Act → Observe → Verify → Record → Cover), a bug bar (reproducible, user-affecting, persistent), and a hunting list of "things humans notice that machines miss" — then gets out of the way.

click_what("Login button"), not click(7). Element indices are a leaky abstraction even within one observe. A capable agent describes what it wants by what it is, and the resolver maps that to the right element — refusing to misclick on ambiguity rather than guessing.

Project layout

argus/
├── mcp_server.py     # tool surface + role instructions + reproduction-receipt engine
├── browser.py        # Playwright backend: DOM/ARIA extraction, capsule/replay
├── resolver.py       # description → element (web + screen)
├── reporter.py       # HTML + JSON + JUnit + SARIF
├── detector.py       # console + network capture (only)
├── cli.py            # argus (explore) + argus-regression
├── bench/            # deterministic ceiling + real-LLM recall harness
└── screen/           # macOS AX backend, permissions, safety
test-site/            # BuggyTasks  (22 mechanical bugs)
human-eye-fixture/    # DarkShop    (12 human-eye bugs)

MIT licensed · Built by Yichen Wu · Issues and PRs welcome