Skip to main content
Glama
ironclawdevs27

argus-qa

by ironclawdevs27
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Argus — AI-Powered Automated QA

npm MCP Server Harness License: MIT

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

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.

Related MCP server: AWT (AI Watch Tester)

What Argus Catches

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

Category

What it detects

JavaScript

Uncaught exceptions, unhandled promise rejections, console.error on critical routes

Network & API

HTTP 5xx, 401/403 auth failures, duplicate API calls (infinite loops), 4xx errors, broken links

Performance

LCP > 2500ms, CLS > 0.1, TTFB > 800ms, slow APIs > 1s/3s, payloads > 500KB/2MB, JS bundles > 500KB

Accessibility

axe-core (80+ WCAG rules), color-blind simulation, missing ARIA, keyboard focus, heading hierarchy

SEO

Missing meta description, OG tags, canonical, viewport, h1

Security

Auth tokens in localStorage/URL, eval(), missing CSP/X-Frame-Options, CSP violations, missing SRI on external scripts, source map exposure, open redirects, npm CVEs

CSS

Cascade overrides, component style leaks, unused rules, React inline style conflicts

Content

null/undefined as visible text, lorem ipsum, broken images, empty data lists

Responsive

Horizontal overflow at 375px/768px, touch targets < 44×44px

Memory

Detached DOM nodes via V8 heap snapshot, heap growth across navigation

Visual

Pixel-level screenshot regression via pixelmatch (≥0.1% warning, ≥5% critical)

Figma

Design-to-implementation fidelity — 13 property types (color, spacing, typography, shadows, etc.)

Forms

Missing required, autocomplete, aria-describedby; unlabelled inputs

Fonts

FOIT, FOUT, missing fallbacks, slow loads > 1s, suboptimal formats

Motion

prefers-reduced-motion violations, autoplay without pause controls

Network baseline

New requests, missing requests, status-code regressions vs saved HAR baseline

Environment diff

Dev vs staging — screenshot diff, DOM changes, console/network regressions

And every finding is post-processed with:

Post-processor

What it adds

Intelligent baseline filtering

Findings that flip-flop across runs are tagged noisy and downgraded to info — pure cross-run heuristics, no API calls (ARGUS_NOISE_FILTER=0 to disable)

Root cause linking

New findings are annotated with the recent git commits and files most likely to have caused them (ARGUS_ROOT_CAUSE=0 to disable)

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.

MCP Tools

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

Tool

Description

argus_audit

Fast pass — JS, network, accessibility, SEO, security, CSS, content

argus_audit_full

Deep pass — adds Lighthouse, responsive checks, memory leak detection, hover-state bugs

argus_compare

Diff dev vs staging — screenshots, findings delta, environment regressions

argus_get_context

Capture everything broken on the open tab for Claude to diagnose

argus_watch_snapshot

Snapshot the open tab without navigating (preserves auth/form state)

argus_last_report

Return last JSON report without re-running

argus_design_audit

Figma URL → 13 design-token finding types (color, spacing, typography, shadows, etc.)

argus_visual_diff

Screenshot baseline comparison. Pass updateBaseline: true to reset.

argus_pr_validate

Fetch GitHub PR diff → map changed files to affected routes → targeted audit → { blocked, findings }

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

Full Setup

Prerequisites

Requirement

Version

Node.js

v20.19+

Chrome

Stable (desktop or headless)

Claude Code

Latest (npm install -g @anthropic-ai/claude-code)

Slack workspace

Optional — omit for local report.html mode

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)

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          # 61 unit tests — no Chrome required
npm run test:harness       # 144-block correctness harness — requires Chrome
npm run test:harness:log   # same, but tees full output to harness-results.txt

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

Secret

Required

Value

TARGET_STAGING_URL

Yes

Your staging base URL

SLACK_BOT_TOKEN

No

xoxb-... token (omit for HTML-only mode)

SLACK_CHANNEL_CRITICAL

No*

Channel ID (needed when Slack is configured)

SLACK_CHANNEL_WARNINGS

No*

Channel ID

SLACK_CHANNEL_DIGEST

No*

Channel ID

GITHUB_TOKEN

No

Auto-injected by Actions for PR comments + Check Runs

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

Variable

Default

Description

TARGET_DEV_URL

—

Required. Base URL of your dev environment

TARGET_STAGING_URL

—

Staging URL — enables argus_compare; omit for CSS-only mode

SLACK_BOT_TOKEN

—

xoxb-... token. Omit for local report.html mode

SLACK_SIGNING_SECRET

—

For /argus-retest slash command verification

SLACK_CHANNEL_CRITICAL

—

Channel ID for critical bugs

SLACK_CHANNEL_WARNINGS

—

Channel ID for warnings

SLACK_CHANNEL_DIGEST

—

Channel ID for info / daily digest

PORT

3001

Slack slash-command server port

REPORT_OUTPUT_DIR

./reports

Where to write JSON reports

ARGUS_CONCURRENCY

1

Parallel MCP clients for route crawling

ARGUS_LOG_LEVEL

info

trace / debug / info / warn / error

ARGUS_LOG_PRETTY

—

Set 1 for human-readable logs in dev

ARGUS_RETRY_ATTEMPTS

3

Max retries for navigate/fill MCP calls

ARGUS_WATCH_INTERVAL_MS

1000

Watch mode poll interval (ms)

ARGUS_WATCH_UI_PORT

3002

Watch mode web dashboard port

ARGUS_SOURCE_DIR

—

App source path — enables env-var / feature-flag / dead-route analysis

ARGUS_ENV_FILE

—

Path to app .env for codebase cross-reference

SCREENSHOT_DIFF_THRESHOLD

0.5

Pixel diff % threshold for environment comparison

GITHUB_TOKEN

—

For PR comments + Check Runs

GITHUB_REPOSITORY

—

owner/repo format

GITHUB_PR_NUMBER

—

Auto-injected by Actions from PR context

ARGUS_CRITICAL_THRESHOLD

1

New criticals before blocking merge (0 = never block)

ARGUS_DIFF_IMAGE_URL

—

Visual diff image URL to embed in PR comment

OTEL_EXPORTER_OTLP_ENDPOINT

—

OTLP collector for Jaeger / Grafana Tempo

FIGMA_API_TOKEN

—

Required for argus_design_audit

FONT_SLOW_MS

1000

Slow web font load threshold (ms)

A11Y_CONTRAST_AA

4.5

WCAG AA min contrast ratio for CVD simulation

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

How Argus Differs From Playwright / Cypress

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

Playwright / Cypress

Argus

Purpose

Test your logic and API contracts

Catch what the user actually sees

What it catches

Regressions in behavior

CSS drift, visual regressions, API loops, console noise, perf budgets

When it runs

In your test suite

Continuously, on the live running app

Setup

Write test files

Configure routes in targets.js

Output

Pass / fail

Structured Slack reports with screenshots

Known Limitations

All 738 harness assertions pass (738/738) — there are currently no known MCP- or Chrome-layer restrictions. Soft assertions (Lighthouse, performance traces) still require non-headless Chrome and are skipped in headless CI.

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/           — 144-block correctness harness, 738 hard assertions, 60 fixture pages
test/unit/              — 61 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

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

Contributing

  1. Fork the repo and create a branch

  2. npm run test:unit — verify without Chrome (61 tests)

  3. npm run test:harness — full integration coverage (requires Chrome on port 9222)

  4. Open a PR — Argus audits itself via the CI workflow

License

MIT © ironclawdevs27

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

argus-qa.com · npm · MCP Registry

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
1dResponse time
2dRelease cycle
6Releases (12mo)
Commit activity

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ironclawdevs27/Argus'

If you have feedback or need assistance with the MCP directory API, please join our Discord server