Argus — Eyes and Hands for AI Agents

AI agents can write code — but they can't see what's happening in the browser.
Argus gives them eyes and hands: detect errors, inspect state, interact with pages, run tests, and fix issues autonomously.

---

The Problem

You know this loop:

You: "Fix the login page" Agent: changes 3 files You: refreshes browser — white screen, console full of errors You: copies error, pastes it back — "It's showing TypeError on line 42" Agent: tries again You: refreshes — button renders but doesn't work You: opens DevTools, copies the network error, screenshots the layout, describes what's wrong in words...

Repeat 5–10 times. Your agent is powerful — but blind. It can't see the browser, so you become the middleman between the AI and your running app.

This loop kills productivity.

The Solution

Argus gives AI agents eyes and hands in the browser.

Your agent can now:

• See console errors, network failures, screenshots, component state
• Act by clicking buttons, filling forms, navigating pages, running JavaScript
• Test with visual regression, responsive audits, accessibility checks
• Debug by inspecting React/Vue/Svelte/Angular components, mapping errors to source code

All through MCP — no custom APIs, no complex setup. Just install the extension, connect, and start talking to your agent.

Features

• 31 MCP tools — observe, act, inspect, test, measure
• Natural language E2E testing — write tests in plain English, no code
• Works with any MCP client — Cursor, Claude Code, Windsurf, Cline, etc.
• Secure by default — all data stays local, auth tokens, site filtering
• Zero config — auto-connects, IDE starts server automatically
• Visual regression — pixel-perfect UI testing
• Accessibility audits — catch a11y issues automatically
• Framework-aware — inspects React/Vue/Svelte/Angular components

Natural Language E2E Testing

Write tests in plain English in a markdown file — no framework, no selectors, no test code:

## Test: Login flow
1. Go to http://localhost:3000/login
2. Type "[email protected]" in the email field
3. Click Sign In
4. Verify the heading says "Welcome back, Admin"
5. Make sure there are no console errors

Then tell your agent: "Read tests/e2e.md and run all the tests."

The agent executes each step using Argus tools — clicking, typing, navigating, screenshotting, checking errors — and reports results. No Playwright, no Selenium, no brittle selectors. Anyone on your team can write tests.

See argus-demo for a full 18-test example covering search, cart, checkout, visual regression, responsive layout, and accessibility.

MCP Compatibility

Works with any MCP-compatible IDE or client:

• Cursor — Add to .cursor/mcp.json
• Claude Code — claude mcp add argus
• Claude Desktop — Add to claude_desktop_config.json
• Windsurf — Configure in settings
• Cline — Add to config
• Any MCP client — Standard stdio or SSE transport

Your IDE automatically starts the Argus server — no terminal commands needed.

MCP Tools

31 tools across 5 categories:

Category	What the agent can do
Observe	Console errors · network failures · screenshots · page info · element details · error source mapping
Act	Click · type · scroll · navigate · fill forms · run JS · highlight elements
Inspect	React / Vue / Svelte / Angular component props, state, hooks, context
Test	Visual regression (pixel-diff) · responsive audit (mobile / tablet / desktop) · accessibility
Runtime	Web Vitals · localStorage · sessionStorage · cookies

Observation (10 tools)

Tool	Description
get_console_errors	JS errors with stack traces
get_console_logs	Console output (log, warn, info, debug)
get_network_failures	Failed HTTP requests (4xx, 5xx)
get_network_log	All recent network requests
get_screenshot	Browser screenshot as native image
list_screenshots	Timeline of captured screenshots with metadata
get_selected_element	Right-click captured element — selector, styles, HTML
get_page_info	Current page URL, title, viewport
get_error_source_context	Parse stack trace to file:line:column
clear_context	Clear stored context

Browser Actions (8 tools)

Tool	Description
click_element	Click any element by CSS selector
type_text	Type into inputs (React/Vue compatible)
scroll_to	Scroll to element, position, or direction
navigate_to	Navigate to any URL
get_text	Read text content of any element
run_javascript	Execute JS in page context
highlight_element	Highlight element with colored outline
wait_for_element	Wait for element to appear in DOM

Framework Inspection (2 tools)

Tool	Description
detect_framework	Detect React, Vue, Svelte, Angular, Next.js, Nuxt, jQuery
inspect_component	Read component props, state, hooks, context

Visual Regression (4 tools)

Tool	Description
snapshot_baseline	Save current screenshot as named baseline
compare_with_baseline	Pixel-diff current vs baseline
list_baselines	List all saved baselines
delete_baseline	Delete a saved baseline

Runtime (7 tools)

Tool	Description
fill_form	Fill multiple form fields in one call
capture_at_viewport	Resize browser + screenshot
responsive_audit	Capture at mobile, tablet, desktop breakpoints
get_performance_metrics	Web Vitals, memory, resource counts
get_storage	Read localStorage / sessionStorage
get_cookies	List cookies for current domain
get_accessibility_issues	Audit for missing alt text, labels, contrast

Comparison

Feature	Argus	Playwright/Selenium	Browser DevTools	Puppeteer
AI agent integration	✅ Native MCP	❌ Manual scripting	❌ Manual inspection	❌ Manual scripting
Natural language tests	✅ Yes	❌ Code required	❌ N/A	❌ Code required
Component inspection	✅ React/Vue/Svelte	❌ No	⚠️ DevTools only	❌ No
Visual regression	✅ Built-in	⚠️ Requires setup	❌ No	⚠️ Requires setup
Zero config	✅ Auto-connects	❌ Complex setup	✅ Built-in	⚠️ Requires setup
Framework-aware	✅ Yes	❌ No	⚠️ DevTools only	❌ No

Argus is designed for AI agents first — while Playwright and Selenium are powerful, they require writing code. Argus lets you describe what you want in plain English, and your agent figures out how to do it.

Quick Start

Prerequisites: Python 3.11+, Node.js 18+, Chrome, and an MCP-compatible IDE (Cursor, Claude Code, etc.)

1. Clone & Install

git clone https://github.com/itachi-hue/argus.git
cd argus

# Server
cd server
pip install -e .

# Extension
cd ../extension
npm install
npm run build

2. Add to Your IDE

Your IDE starts the Argus server automatically — no need to run anything in the terminal.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "argus": {
      "command": "python",
      "args": ["-m", "argus"],
      "cwd": "/absolute/path/to/argus/server"
    }
  }
}

Important: Replace /absolute/path/to/argus/server with the actual path to the server/ folder on your machine (e.g. C:/Users/you/argus/server on Windows or /home/you/argus/server on Linux/Mac).

Restart Cursor. Look for argus with a green dot under Settings → MCP.

Claude Code

cd /absolute/path/to/argus/server
claude mcp add argus -- python -m argus

Replace /absolute/path/to/argus/server with the actual path.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "argus": {
      "command": "python",
      "args": ["-m", "argus"],
      "cwd": "/absolute/path/to/argus/server"
    }
  }
}

Replace /absolute/path/to/argus/server with the actual path.

Other MCP Clients

stdio (local, default):

command: python -m argus
working directory: /absolute/path/to/argus/server

SSE (remote):

ARGUS_TRANSPORT=sse python -m argus
# Connect your client to http://127.0.0.1:42777/mcp/sse

3. Load the Chrome Extension

1. Open chrome://extensions in Chrome
2. Enable Developer mode (toggle in top-right)
3. Click Load unpacked → select the extension/ folder

4. Connect

1. Open any page in Chrome (e.g. your app at localhost:3000)
2. Click the Argus extension icon → Connect

That's it. The extension auto-detects the running server and connects instantly.

If auto-connect isn't available (e.g. another extension already claimed it), expand Manual setup in the popup to paste a token from http://127.0.0.1:42777/api/pair.

5. Use It

Open your web app in Chrome and talk to your agent:

• "Check the browser for errors and fix them"
• "Take a screenshot and fix the layout"
• "Click the login button and see what happens"
• "Run an accessibility audit on the page"

Security

• All data stays on your machine — server binds to 127.0.0.1 only
• Auth token required on every request (constant-time comparison)
• Auto-connect is first-come-first-served — locks after the first extension connects
• WebSocket authenticated via token on handshake
• Authorization, Cookie, Set-Cookie headers automatically redacted
• Request/response bodies truncated · in-memory only · rate limited
• Site filtering — configurable allowlist / denylist in extension settings to control which sites Argus can observe

Configuration

Variable	Default	Description
ARGUS_TRANSPORT	stdio	stdio, sse, or all
ARGUS_PORT	42777	HTTP server port
ARGUS_AUTH_TOKEN	auto-generated	Auth token
ARGUS_MAX_ERRORS	100	Max errors in buffer
ARGUS_MAX_SCREENSHOTS	15	Max screenshots stored
ARGUS_RATE_LIMIT	120	Max requests/minute

Roadmap

Near-term

• Chrome Web Store — One-click install for instant usage
• Firefox extension — Cross-browser support
• Safari extension — Full browser coverage
• Record & replay — Capture user flows and replay them automatically
• CI/CD integration — Run natural language tests in GitHub Actions
• Team features — Share baselines, test results, and dashboards
• More frameworks — Better support for Svelte, Solid, Qwik

Future directions

• Desktop apps — Electron and native desktop support
• Mobile observability — iOS and Android monitoring
• Terminal / CLI monitoring — Observe command-line tools and scripts
• Self-healing workflows — Automatically detect and fix issues across platforms

Have ideas? Open an issue!

Development

# Server
cd server
pip install -e ".[dev]"
pytest tests/ -v              # run tests
ruff check src/ tests/        # lint
ruff format src/ tests/       # format

# Extension
cd extension
npm install
npm run build                 # production build
npm run watch                 # dev mode with auto-rebuild

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Open a PR

License

MIT License — © 2026 Vivek Rao. See LICENSE for details.