╔╗╔╔═╗╔═╗╦  ╦
║║║║╣ ╠╦╝╚╗╔╝
╝╚╝╚═╝╩╚═ ╚╝

Autonomous QA Agent for Web Applications

Observe → Decide → Act → Detect

What is Nerv?

Nerv is a CLI tool that autonomously explores web applications and finds bugs. Point it at a URL — it launches a browser, navigates pages, clicks buttons, fills forms, and reports every issue it finds.

Two exploration modes:

• AI-guided (via 5-Model Cloud Roster) — qwen3-coder-next decides what to click, type, and explore, while ALL models enhance and validate reports independently with synthesis
• Systematic (fallback) — BFS crawl of all links, buttons, and forms

Bug detection covers:

• 🔴 Console errors & unhandled JS exceptions
• 🌐 Network failures (4xx, 5xx, timeouts)
• 🖼️ Broken images
• ♿ Accessibility issues (missing alt text, unlabeled inputs)
• ⚡ Performance problems (slow TTFB, slow DOM load)
• 🔒 Security red flags (HTTP forms, inline handlers)
• 📐 UI issues (horizontal overflow)

Quick Start

# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Run a scan
node bin/nerv.js run https://example.com

Global install (optional)

npm link
nerv run https://example.com

Usage

nerv run <url> [options]

Options:
  --headed             Run browser visibly (not headless)
  --max-actions <n>    Maximum actions to perform (default: 30)
  --max-time <s>       Maximum time in seconds (default: 700)
  --model <name>       Ollama model to use (default: mistral)
  --no-ai              Disable AI, use systematic exploration only
  -o, --output <dir>   Output directory for reports (default: ./reports)
  -v, --verbose        Enable verbose debug logging

Examples

# Quick scan with defaults
nerv run https://myapp.com

# Thorough scan with visible browser
nerv run https://myapp.com --headed --max-actions 50 --max-time 700

# Systematic scan (no Ollama needed)
nerv run https://myapp.com --no-ai --max-actions 40

# Use deepseek-coder instead of mistral
nerv run https://myapp.com --model deepseek-coder

AI Mode (Multi-Model Integration)

When you use the --ai flag, Nerv will automatically:

1. Detect if Ollama is installed on your system
2. Install Ollama if missing (works on Windows, macOS, and Linux)
3. Start the Ollama daemon in the background
4. Iteratively Pull all 5 cloud models if they are missing (qwen3-coder-next:cloud, kimi-k2.5:cloud, glm5:cloud, qwen3.5:397b:cloud, gemma4:31b:cloud)

# Just use --ai — Nerv handles the rest
nerv https://example.com --ai

No manual setup required. If Ollama or the models are missing, Nerv will prompt you to install them automatically.

Manual install (optional): If you prefer to set up Ollama yourself, visit ollama.com and run ollama pull qwen3-coder-next:cloud.

Nerv auto-detects Ollama. If it's not running or --ai is not passed, Nerv falls back to systematic rule-based mode.

Report Format

Reports are saved as JSON in ./reports/:

{
  "meta": {
    "tool": "Nerv QA Agent",
    "version": "2.0.1",
    "timestamp": "2026-04-14T...",
    "targetUrl": "https://example.com"
  },
  "summary": {
    "totalBugs": 5,
    "critical": 0,
    "high": 2,
    "medium": 2,
    "low": 1,
    "byType": {
      "console_error": 2,
      "network_error": 1,
      "accessibility": 2
    },
    "pagesVisited": 8,
    "actionsPerformed": 30,
    "durationSeconds": 45
  },
  "bugs": [ ... ],
  "visitedUrls": [ ... ]
}

Architecture

bin/nerv.js          CLI entry point (Commander.js)
src/
├── index.js         Main orchestrator
├── agent.js         Agent loop (observe → decide → act → detect)
├── crawler.js       Playwright browser control
├── ollama.js        Ollama LLM integration
├── detector.js      Bug detection (console, network, DOM, perf, security)
├── reporter.js      JSON report generation
└── logger.js        ANSI-colored console output

Requirements

• Node.js ≥ 18
• Playwright (auto-installed)
• Ollama (optional, for AI mode)
  • Recommended models: mistral, deepseek-coder
  • Works on 8GB Mac

License

MIT