Argus

Por qué existe Argus

Los agentes de IA ahora escriben la mayor parte del código — y juzgan su propio trabajo por si compila y parece terminado, no por lo que realmente sucede en el navegador. La excepción no capturada en el tercer clic. El formulario que envía credenciales por HTTP. El LCP de 4 segundos. El botón que desapareció en modo oscuro. El endpoint de API golpeado en un bucle infinito.

Argus cierra esa brecha. Conduce un Chrome real (a través del Protocolo Chrome DevTools) contra tu aplicación que se ejecuta localmente y entrega al agente — o a ti — un informe de errores estructurado y clasificado por severidad. El agente corrige; Argus vuelve a verificar; el bucle se cierra antes de que el código salga de tu máquina.

Inicio rápido

Sin instalación. npx obtiene Argus en la primera ejecución.

1 — Añade dos líneas a .mcp.json en la raíz de tu proyecto:

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

O a través de la CLI de Claude Code:

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

2 — Inicia Chrome (detecta automáticamente tu Chrome, establece las banderas correctas):

npx -y -p argusqa-os argus-chrome

# 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

3 — Pregunta a tu agente:

Run argus_audit on http://localhost:3000

Eso es todo. Los hallazgos vuelven estructurados y clasificados por severidad — en la conversación, a Slack, o como un report.html local. ¿Algo no funciona? npx -y -p argusqa-os argus-doctor diagnostica tu configuración con un solo comando.

El bucle de corrección

Así se ve Argus dentro de una sesión de codificación agéntica:

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_context compara con la instantánea anterior, para que el agente sepa exactamente qué corrigió, qué rompió y qué queda — sin releer muros de salida.

"Pero mi agente ya puede manejar un navegador…" — puede. Manejar no es juzgar. Un MCP de navegador en bruto (Playwright MCP, chrome-devtools-mcp desnudo) le da al agente manos y ojos; el agente debe entonces re-derivar qué verificar en cada sesión, quemando contexto en la exploración de registros de consola. Argus es la capa de juicio encima: 149 tipos de hallazgos codificados con umbrales, política de severidad, líneas base entre ejecuciones, filtrado de inestabilidad, deduplicación, pistas de causa raíz — devueltos en una sola llamada, redactados por defecto.

Lo que Argus detecta

32 motores de análisis, 149 tipos de problemas distintos, cero mantenimiento de archivos de prueba:

Y cada hallazgo se procesa posteriormente con:

Todos los hallazgos se clasifican como critical / warning / info y se enrutan al canal de Slack correcto — o se muestran en el informe HTML local. Para tablas de severidad por hallazgo y métodos de detección, consulta REFERENCE.md.

Compatible con tu stack

Argus audita la salida renderizada, no tu código fuente — por lo que es agnóstico de frameworks por construcción. Si se ejecuta en Chrome, Argus puede auditarlo:

Límites honestos: solo renderizado Chrome/Chromium (sin diferencias de motor Safari/Firefox), solo web (sin aplicaciones móviles nativas ni de escritorio), y los servicios backend se verifican a través del tráfico que genera la página — no como suites de prueba de API independientes.

Confidencialidad — Límite de salida de Aegis

Activado por defecto. Argus audita tu aplicación en busca de secretos y vulnerabilidades — por lo que sus hallazgos son exactamente los datos que menos quieres que salgan de tu máquina. Aegis los redacta en cada límite externo antes de que crucen. Para equipos que adoptan agentes de IA, esta es la diferencia entre "usamos una herramienta de QA con IA" y "podemos decirle a nuestro líder de seguridad exactamente por qué es seguro".

Un hallazgo enviado a un destino externo — una respuesta de herramienta MCP (que llega a la ventana de contexto del agente llamante y transita al proveedor de modelos de ese agente), un mensaje de Slack, un comentario de PR de GitHub con sus anotaciones de ::error, el informe HTML alojado/CI, o los registros de CI — se reduce a una proyección de necesidad de saber: un hallazgo sensible cruza como su type + route + severity + un marcador de 🔒, y nunca su carga útil bruta (message, evidence, cuerpos de solicitud/respuesta, encabezados, cookies, stack). Las URLs se proyectan con la cadena de consulta eliminada (los tokens se esconden allí). Un hallazgo benigno conserva su mensaje — pero ese mensaje aún se limpia de cualquier secreto o PII incrustado accidentalmente.

Esto implementa las mitigaciones de OWASP LLM02:2025 — Divulgación de información sensible (minimización de datos, redacción, filtrado de salida por denegación por defecto) en los propios límites de Argus. Una bóveda de rehidratación opcional, solo local (ARGUS_REDACT_VAULT=1), puede acuñar tokens reversibles y sin información para artefactos estables en diferencias — re-inflar localmente con npm run report:rehydrate. El cambio completo de comportamiento está documentado en CHANGELOG.md.

Herramientas MCP

Pregunta a Claude (o a cualquier cliente MCP) — sin necesidad de terminal:

Cada respuesta de herramienta se proyecta a través del límite de salida de Aegis antes de llegar al agente, y lleva un aviso opcional de redaction ({ redacted, total }) cuando se retuvo detalle sensible.

Ejemplos de 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

Probado en batalla, no por vibraciones

La propia corrección de Argus se aplica de la misma manera que audita la tuya:

• 998/998 aserciones estrictas en un arnés de integración de 171 bloques que maneja Chrome real contra 64 páginas de prueba — incluidos controles negativos por categoría (cero sobre-disparos), esquemas de respuesta dorados para las 9 herramientas MCP, y un canario de deriva ascendente que detecta cambios de API de chrome-devtools-mcp en el momento del aumento de versión
• 562 pruebas unitarias sin Chrome (Vitest) + fuzzing de parser basado en propiedades
• npm audit: 0 vulnerabilidades · CodeQL + Dependabot en cada PR · Socket.dev: 100/100/100 en vulnerabilidad/calidad/licencia
• Archivos de sesión y tokens capturados escritos 0600, solo propietario

Configuración completa

Prerrequisitos

Opción A — Servidor MCP (recomendado para usuarios de Claude Code)

No se necesita instalación local. Usa el Inicio rápido de arriba y luego añade tu URL objetivo:

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

Opcional — Notificaciones de Slack:

1. api.slack.com/apps → Crear nueva app → nómbrala BugBot
2. OAuth y Permisos → Ámbitos de token de bot: chat:write, files:write, files:read
3. Instala en el espacio de trabajo → copia el token xoxb-...
4. Crea los canales #bugs-critical, #bugs-warnings, #bugs-digest y ejecuta /invite @BugBot en cada uno

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

Sin Slack: Argus genera automáticamente reports/report.html y lo abre en tu navegador — cero configuración adicional.

Opción B — Paquete npm (CI / dependencia de desarrollo)

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

Opción C — Clonar el repositorio (contribuidores / código fuente completo)

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

Configuración manual (omite el asistente):

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

Luego configura tus rutas en 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 — los errores en esta ruta van a #bugs-critical
• waitFor — selector CSS que Argus espera antes de capturar (señala que la página está lista)

Comandos CLI

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)

Modo de observación — monitoreo en vivo mientras tú (o tu agente) desarrollas:

# 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

Comando de barra de Slack (bajo demanda desde cualquier canal):

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

Para exponer el servidor mediante túnel: cloudflared tunnel --url http://localhost:3001 (gratis, sin cuenta requerida). Establece la URL resultante como URL de solicitud en Slack App → Slash Commands.

GitHub Actions CI — Puerta de PR

Argus se distribuye como una acción compuesta de GitHub: en cada PR asigna el diff a las rutas afectadas, las audita y bloquea la fusión solo en hallazgos que introduce el PR (consciente de la línea base) — con un comentario de PR idempotente y una Check Run.

Añade a los secretos de tu repositorio (Settings → Secrets → Actions):

El workflow incluido se ejecuta al hacer push a main, diariamente a las 6 AM UTC, y con activación manual. Si se encuentran problemas críticos, el pipeline falla.

Variables de Entorno

Solución de Problemas

Primer recurso para cualquier problema: npx -y -p argusqa-os argus-doctor — verifica la accesibilidad de Chrome, la validez de la configuración MCP y las claves de entorno requeridas, e imprime la solución exacta para cada fallo.

Chrome DevTools MCP no se conecta

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

Los mensajes de Slack no se publican

• El token debe comenzar con xoxb- (no xoxp-, xoxe- o xapp-)
• Ejecuta /invite @BugBot en cada canal
• Ámbitos requeridos: chat:write, files:write, files:read

Las capturas de pantalla están en blanco

• La página no se ha estabilizado — aumenta pageSettleMs en src/config/targets.js o añade un selector waitFor para la ruta

/argus-retest devuelve "dispatch_failed"

• La URL del túnel cambió — actualiza la URL de solicitud en Slack App → Slash Commands y reinstala

El análisis CSS devuelve resultados vacíos

• La página puede estar detrás de autenticación — asegúrate de haber iniciado sesión en la instancia de Chrome que Argus controla

El pipeline de CI falla inmediatamente

• Chrome puede no iniciar lo suficientemente rápido — aumenta sleep 3 a sleep 5 en .github/workflows/argus.yml

Cómo Argus se Diferencia de Playwright / Cypress

Argus es una capa complementaria, no un reemplazo para pruebas unitarias o E2E:

Limitaciones Conocidas

Las 998 aserciones del harness pasan (998/998) — actualmente no hay restricciones conocidas a nivel MCP o Chrome. Lighthouse se ejecuta en headless (después de la corrección del argumento lighthouse_audit); las aserciones suaves restantes (trazas de rendimiento, crecimiento de heap dependiente de GC) se promueven a aserciones duras contadas solo en el carril semanal estricto-suave (harness-strict.yml) mediante ARGUS_HARNESS_STRICT_SOFT. Límites de alcance: solo Chrome/Chromium, solo aplicaciones web — consulta Funciona con tu Stack.

Argus Alojado — Miembros Fundadores

¿Quieres auditorías sin ejecutar Chrome o npm — con historial, tendencias, horarios y un panel de equipo? Argus Cloud está en acceso temprano para miembros fundadores: $19/mes, bloqueado para siempre (regular $29).

Conviértete en miembro fundador → argus-qa.com

El motor de código abierto en esta página permanece MIT y con todas las funciones, siempre — el nivel alojado vende conveniencia y memoria, nunca detecciones.

Estructura del Proyecto

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

Mapa de código fuente completo → CLAUDE.md · Referencia MCP/DSL → SKILL.md

Contribuciones

Las contribuciones son bienvenidas — páginas de fixtures, nuevas categorías de detección, descubrimiento de rutas de frameworks, documentación. Comienza con CONTRIBUTING.md.

1. Haz un fork del repositorio y crea una rama
2. npm run test:unit — verifica sin Chrome (562 pruebas)
3. npm run test:harness — cobertura completa de integración (requiere Chrome en el puerto 9222)
4. Abre un PR — Argus se audita a sí mismo mediante el workflow de CI

Licencia

MIT © ironclawdevs27