Argus

<div align="center">

# Argus — AI-Powered Automated QA

[![npm](https://img.shields.io/npm/v/argusqa-os?color=7C3AED)](https://www.npmjs.com/package/argusqa-os)
[![MCP Server](https://glama.ai/mcp/servers/ironclawdevs27/Argus/badges/card.svg)](https://glama.ai/mcp/servers/ironclawdevs27/Argus)
[![Harness](https://img.shields.io/badge/harness-688%2F688-4ADE80)](test-harness/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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](#quick-start) · [Features](#what-argus-catches) · [Setup](#full-setup) · [MCP Tools](#mcp-tools) · [CLI Commands](#cli-commands) · [Troubleshooting](#troubleshooting) · [Full Reference](REFERENCE.md)

</div>

---

## Quick Start

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

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

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

Or via Claude Code CLI:

```bash
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:**

```bash
# 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.

---

## 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](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](#quick-start) above, then add your target URL:

```env
# .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](https://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

```env
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)

```bash
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)

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

**Manual setup (skip the wizard):**

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

Then configure your routes in [src/config/targets.js](src/config/targets.js):

```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

```bash
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       # 142-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:

```bash
# 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 |
| `S