Argus — AI-Powered Automated QA

Argus catches the bugs your test suite misses — visual regressions, API loops, CSS drift, console noise, accessibility failures, and more — and delivers rich reports to Slack (or a local HTML dashboard).

Quick Start · Features · Setup · MCP Tools · CLI Commands · Troubleshooting · Full Reference

What Argus Catches

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

And every finding is post-processed with:

All findings are classified as critical / warning / info and routed to the right Slack channel — or surfaced in the local HTML report. For per-finding severity tables and detection methods, see REFERENCE.md.

Confidentiality — Aegis Egress Boundary

Default ON. Argus audits your app for secrets and vulnerabilities — so its findings are exactly the data you least want leaving your machine. Aegis redacts them at every external boundary before they cross.

A finding sent to an external sink — an MCP tool response (which lands in the calling agent's context window and transits to that agent's model provider), a Slack message, a GitHub PR comment + its ::error annotations, the hosted/CI HTML report, or CI logs — is reduced to a need-to-know projection: a sensitive finding crosses as its type + route + severity + a 🔒 marker, and never its raw payload (message, evidence, request/response bodies, headers, cookies, stack). URLs are projected with the query string stripped (tokens hide there). A benign finding keeps its message — but that message is still scrubbed for any accidentally-embedded secret or PII.

This implements the OWASP LLM02:2025 — Sensitive Information Disclosure mitigations (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 with npm run report:rehydrate. Full behavior change is documented in CHANGELOG.md.

MCP Tools

Ask Claude (or any MCP client) — no terminal required:

Every tool response is projected through the Aegis egress boundary before it reaches the agent, and carries an optional redaction rider ({ redacted, total }) when sensitive detail was withheld.

Example prompts:

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

CLI Commands

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          # 495 unit tests — no Chrome required
npm run test:harness       # 168-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 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.

GitHub Actions CI

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

The included workflow runs on push to main, daily at 6 AM UTC, and on manual trigger. If critical issues are found, the pipeline fails.

Environment Variables

How Argus Differs From Playwright / Cypress

Argus is a complementary layer, not a replacement for unit or E2E tests:

Project Structure

src/
  argus.js              — single-page audit entry point
  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
  config/targets.js     — routes, thresholds, auth steps
  cli/
    init.js             — argus init interactive setup wizard
    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
    pr-validate.js      — headless CI entry point for GitHub Actions
test-harness/           — 168-block correctness harness, 978 hard assertions, 64 fixture pages
test/unit/              — 495 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

Full source map → CLAUDE.md · MCP/DSL reference → SKILL.md

Quick Start

No install required. npx auto-downloads Argus on first run.

Step 1 — Add to .mcp.json in your project root:

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

Or via Claude Code CLI:

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

Step 2 — Start Chrome with remote debugging:

# 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

Step 3 — Run an audit:

Run argus_audit on http://localhost:3000

Argus scans your app and either posts findings to Slack or opens a local report.html. That's it.

Full Setup

Prerequisites

Option A — MCP Server (recommended for Claude Code users)

No local install needed. Use the Quick Start above, 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

Optional — Slack notifications:

1. api.slack.com/apps → Create New App → name it BugBot
2. OAuth & Permissions → Bot Token Scopes: chat:write, files:write, files:read
3. Install to workspace → copy the xoxb-... token
4. Create channels #bugs-critical, #bugs-warnings, #bugs-digest and run /invite @BugBot in each

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

Without Slack: Argus auto-generates reports/report.html and opens it in your browser — zero extra config.

Option B — npm Package (CI / dev dependency)

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

Option C — Clone the Repository (contributors / full source)

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

Manual setup (skip the wizard):

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

Then configure your routes in src/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)

Troubleshooting

Chrome DevTools MCP not connecting

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

Slack messages not posting

• Token must start with xoxb- (not xoxp-, xoxe-, or xapp-)
• Run /invite @BugBot in each channel
• Required scopes: chat:write, files:write, files:read

Screenshots are blank

• Page hasn't settled — increase pageSettleMs in src/config/targets.js or add a waitFor selector for the route

/argus-retest returns "dispatch_failed"

• Tunnel URL changed — update the Request URL in Slack App → Slash Commands and reinstall

CSS analysis returns empty results

• Page may be behind auth — ensure you're logged in on the Chrome instance Argus is controlling

CI pipeline fails immediately

• Chrome may not start fast enough — increase sleep 3 to sleep 5 in .github/workflows/argus.yml

Known Limitations

All 978 harness assertions pass (978/978) — there are currently no known MCP- or Chrome-layer restrictions. Lighthouse now runs in headless (after the lighthouse_audit argument fix); the remaining soft assertions (perf traces, GC-dependent heap-growth) are promoted to counted hard assertions only in the weekly strict-soft lane (harness-strict.yml) via ARGUS_HARNESS_STRICT_SOFT.

License

MIT © ironclawdevs27

Argus Panoptes — the all-seeing giant of Greek mythology who never slept.

argus-qa.com · npm · MCP Registry