Argus

Argus — The QA Layer for AI-Assisted Development

Your AI agent writes the code.Argus checks what it actually built.

One line in your MCP config gives Claude (or any MCP agent) a real Chrome audit engine —67 audit categories · 149 finding types · zero test files to write or maintain.And withAegis, what it findsnever leaks your secrets to the LLM.

Quick Start·The Fix Loop·What It Catches·Your Stack·MCP Tools·Full Setup·Reference

{ "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] }, "argus": { "command": "npx", "args": ["-y", "argusqa-os"] } } }

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest claude mcp add argus -- npx -y argusqa-os

2 — Launch Chrome(auto-detects your Chrome, sets the right flags):

# macOS open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new # Windows (PowerShell) & "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus" # Linux google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox

Run argus_audit on http://localhost:3000

That's it. Findings come back structured and severity-ranked — into the conversation, to Slack, or as a localreport.html. Something off?npx -y -p argusqa-os argus-doctordiagnoses your setup in one command.

This is what Argus looks like inside an agentic coding session:

You: Build me a checkout page with a card form. Agent: [writes the code, dev server renders it] You: Run argus_audit on http://localhost:3000/checkout Argus: ● 2 critical · 3 warnings ● uncaught TypeError in checkout.js (visible on submit) ● form posts over HTTP — security_no_https ▲ card inputs missing labels + autocomplete (a11y/WCAG) ▲ LCP 4.1s — hero image unoptimized ▲ duplicate POST /api/cart ×7 — likely render loop Agent: [fixes all five] You: Run argus_get_context Argus: ✓ resolved: 5 · persisting: 0 · new: 0

argus_get_contextdiffs against the previous snapshot, so the agent knows exactly what it fixed, what it broke, and what remains — no re-reading walls of output.

"But my agent can already drive a browser…"— it can. Driving isn't judging. A raw browser MCP (Playwright MCP, bare chrome-devtools-mcp) gives the agent hands and eyes; the agent must thenre-derive what to checkevery session, burning context on console-log spelunking. Argus is the judgment layer on top: 149 codified finding types with thresholds, severity policy, cross-run baselines, flakiness filtering, dedup, root-cause hints — returned in one call, redacted by default.

32 analysis engines, 149 distinct issue types, zero test-file maintenance:

And every finding is post-processed with:

All findings are classified ascritical/warning/infoand routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, seeREFERENCE.md.

This implements theOWASP LLM02:2025 — Sensitive Information Disclosuremitigations (data minimization, redaction, deny-by-default egress filtering) at Argus's own boundaries. An optional, local-only re-hydration vault (ARGUS_REDACT_VAULT=1) can mint reversible, information-free tokens for diff-stable artifacts — re-inflate locally withnpm run report:rehydrate. Full behavior change is documented inCHANGELOG.md.

Every tool response is projected through theAegis egress boundarybefore it reaches the agent, and carries an optionalredactionrider ({ redacted, total }) when sensitive detail was withheld.

Run argus_audit on http://localhost:3000/checkout Run argus_audit_full on http://localhost:3000/dashboard Run argus_compare Run argus_get_context

- 998/998 hard assertionsacross a 171-block integration harness driving real Chrome against 64 fixture pages — including per-category negative controls (zero over-fire), golden response schemas for all 9 MCP tools, and an upstream-drift canary that catches chrome-devtools-mcp API changes at version-bump time
- 562 Chrome-free unit tests(Vitest) + property-based parser fuzzing
- npm audit: 0 vulnerabilities· CodeQL + Dependabot on every PR ·Socket.dev: 100/100/100 on vulnerability/quality/license
- Session files and captured tokens written0600, owner-only

No local install needed. Use theQuick Startabove, then add your target URL:

# .env in your project root TARGET_DEV_URL=http://localhost:3000 TARGET_STAGING_URL=https://staging.example.com # optional — enables argus_compare

- api.slack.com/apps→ Create New App → name itBugBot
- OAuth & Permissions → Bot Token Scopes:chat:write,files:write,files:read
- Install to workspace → copy thexoxb-...token
- Create channels#bugs-critical,#bugs-warnings,#bugs-digestand run/invite @BugBotin each

SLACK_BOT_TOKEN=xoxb-... SLACK_CHANNEL_CRITICAL=C0000000000 SLACK_CHANNEL_WARNINGS=C0000000001 SLACK_CHANNEL_DIGEST=C0000000002

npm install --save-dev argusqa-os npx argus init # interactive wizard — detects framework, discovers routes, writes .env npm run crawl # run after Chrome is started

git clone https://github.com/ironclawdevs27/Argus.git cd Argus npm install npm run init # interactive setup wizard

cp .env.example .env # Fill in TARGET_DEV_URL and optional Slack tokens

Then configure your routes insrc/config/targets.js:

export const routes = [ { path: '/', name: 'Home', critical: true, waitFor: 'main' }, { path: '/login', name: 'Login', critical: true, waitFor: 'form' }, { path: '/dashboard', name: 'Dashboard', critical: true, waitFor: '[data-testid="dashboard"]' }, { path: '/settings', name: 'Settings', critical: false, waitFor: null }, ];

- critical: true— errors on this route go to#bugs-critical
- waitFor— CSS selector Argus waits for before capturing (signals page-ready)

npm run chrome # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary) npm run doctor # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL npm run crawl # Batch audit of all configured routes npm run compare # Dev vs staging diff (CSS-only if no staging URL) npm run watch # Passive monitor — polls open Chrome tab every 1s npm run report:html # Generate reports/report.html from last JSON audit npm run report:pdf # Export HTML report to A4 PDF (requires: npm install puppeteer) npm run server # Start Slack slash-command server (port 3001) npm run init # Interactive setup wizard npm run test:unit # 562 unit tests — no Chrome required npm run test:harness # 171-block correctness harness — requires Chrome npm run test:harness:log # same, but tees full output to harness-results.txt npm run test:coverage # merged unit + harness coverage gate (requires Chrome)

Watch mode— live monitoring as you (or your agent) develop:

# Terminal 1: start your app npm run dev # Terminal 2: start Argus watcher npm run watch # Ctrl+C → stops monitor and writes reports/report.html

Slack slash command(on-demand from any channel):

/argus-retest https://staging.example.com/checkout

To expose the server via tunnel:cloudflared tunnel --url http://localhost:3001(free, no account required). Set the resulting URL as the Request URL in Slack App → Slash Commands.

Argus ships as a composite GitHub Action: on every PR it maps the diff to affected routes, audits them, and blocks the mergeonly on findings the PR introduces(baseline-aware) — with an idempotent PR comment and a Check Run.

Add to your repo's secrets (Settings → Secrets → Actions):

The includedworkflowruns on push tomain, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest # Restart Claude Code after adding

- Chrome may not start fast enough — increasesleep 3tosleep 5in[.github/workflows/argus.yml