argus

<p align="center"> <img src="src/assets/argus_banner.png" alt="Argus" width="1000" /> </p>

<p align="center"> Chrome DevTools Protocol MCP server — give AI agents eyes into a live browser. </p>

<p align="center"> <img src="https://img.shields.io/badge/MCP-compatible-blue?style=flat-square" alt="MCP compatible" /> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" alt="Node ≥ 18" /> <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" /> </p>

---

Argus connects directly to Chrome via the Chrome DevTools Protocol and exposes browser debugging as MCP tools - no Puppeteer, no Playwright, no browser abstraction layer. Spawn Chrome, attach to tabs, record console output, intercept network requests, inject mocks, and capture screenshots, all from your MCP client.

The name comes from Argus Panoptes - the 100-eyed giant of Greek mythology who could watch everything at once and never fully slept. That's the goal: total visibility into what the browser is doing.

Motivation

Argus came about as part of an ongoing exploration into leveraging agents to reproduce reported issues as well as "manually" debug/record them on the fly. As a result you can expect to see bugs in Argus itself as well as plenty room for improvement and growth over time.

Features

• Console recording — capture console.log/warn/error and unhandled exceptions with stack traces
• Screenshot capture — viewport, full-page, or clipped region, returned as base64 PNG/JPEG
• Network recording — record every request and response including body, headers, timing, and errors
• Network mocking — intercept requests by glob pattern and return custom responses, zero page reload required
• Multi-tab — attach to any number of tabs simultaneously, each with independent recording state
• No dependencies — direct WebSocket connection to Chrome's debug port, no browser driver needed
• Injectable overlay — floating status widget injected into every inspected page showing live counts

Installation

From npm (recommended)

# Install globally
npm install -g @jmsa/argus-mcp
argus-mcp

# Or run without installing
npx @jmsa/argus-mcp

From source

git clone https://github.com/Jmsa/argus
cd argus
npm install
npm run dev

Chrome Canary opens automatically on startup with the Argus welcome page. Connect your MCP client to the stdio transport and start using the tools.

Requirements

• Node ≥ 18
• Google Chrome or Chrome Canary (macOS, Linux, or Windows)

MCP Client Configuration

Claude Code — run this once:

# npm package (recommended)
claude mcp add --transport stdio argus -- argus-mcp

# from source
claude mcp add --transport stdio argus -- npm run dev

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "argus": {
      "type": "stdio",
      "command": "argus-mcp"
    }
  }
}

If running from source instead, use "command": "npm" with "args": ["run", "dev"] and set "cwd" to the project root.

Auto-Launch Behavior

By default, Argus does not automatically launch Chrome when a Claude session starts. Use the browser_launch tool to start Chrome when you need it.

First-run experience

The first time Claude starts with Argus installed, Chrome opens once automatically so you can verify everything is working. A message on the welcome page explains what's happening. After that first session, auto-launch is off unless you enable it.

The auto-launch toggle

The welcome page always shows a Yes / No toggle for auto-launch:

• No (default) — Chrome does not open on Claude start; call browser_launch manually
• Yes — Chrome and the welcome page open automatically at the start of every Claude session

The toggle takes effect immediately and persists across sessions. Your preference is stored in ~/.argus/config.json and can also be edited manually:

{ "autoLaunch": true }

CI / scripted environments

Set ARGUS_NO_LAUNCH=1 to force-skip Chrome launch regardless of the config file. This is useful in CI pipelines or automated environments where a display isn't available.

Tools

Argus exposes 32 tools across eight groups.

Browser

Tool	Description
browser_launch	Spawn a new Chrome instance with remote debugging
browser_connect	Attach to an already-running Chrome via WebSocket URL
browser_disconnect	Disconnect (browser stays open)
browser_status	Check connection state and active tab count

Tabs

Tool	Description
tab_list	List all open page tabs
tab_open	Open a new tab and navigate to a URL
tab_navigate	Navigate an existing tab to a new URL
tab_close	Close a tab by targetId
tab_screenshot	Capture a screenshot (viewport, full-page, or clipped)

Console

Tool	Description
console_start	Begin recording console output and exceptions
console_stop	Stop recording
console_get_logs	Retrieve logs, filterable by type and text
console_clear	Discard captured log entries

Network Recording

Tool	Description
network_start_recording	Enable network capture (requests, responses, bodies)
network_stop_recording	Disable network capture
network_get_requests	Query captured requests (filter by URL, method, status, error)
network_clear_requests	Clear the request history for a tab

Network Mocks

Tool	Description
network_add_mock	Intercept requests matching a glob and return a custom response
network_remove_mock	Remove a mock rule by ID
network_list_mocks	List active mock rules for a tab
network_clear_mocks	Remove all mocks and disable interception

Page

Tool	Description
page_evaluate	Execute JavaScript and return the result
page_reload	Reload the tab (optionally bypassing cache)
page_get_url	Get the current URL and title of a tab

DOM

Tool	Description
dom_query	Query the first element matching a CSS selector and return its properties
dom_query_all	Query all elements matching a CSS selector
dom_click	Click the first element matching a CSS selector (scrolls into view first)
dom_input_value	Set an input's value and dispatch input/change events (React/Vue safe)
dom_get_value	Get the current value of an input element
dom_wait_for	Wait for an element to appear in the DOM (polls every 100ms)

Banner

Tool	Description
banner_update	Push state updates to the Argus banner overlay (recording indicator, counts)
banner_get_screenshots	Retrieve screenshots captured via the banner Screenshot button

Skills

Skills are Claude Code workflows that invoke Argus tools automatically. Install the plugin to get them as slash commands:

/plugin install Jmsa/argus

Skill	Command	Description
debug-session	/argus:debug-session <url>	Capture a complete debugging snapshot — console, network, screenshot
repro-issue	/argus:repro-issue <url> <bug description>	Reproduce a bug using mocks to isolate frontend vs API
network-debug	/argus:network-debug <url>	Investigate failed requests, slow responses, and mock verification

Documentation

• Architecture — project structure and how the pieces connect
• Configuration — Chrome path, port, headless mode, and custom flags
• Network Mocking — glob patterns, mock priority, and request flow

How It Works

MCP Client (Claude, Inspector, etc.)
        │  stdio
        ▼
  Argus MCP Server
        │  CDP over WebSocket
        ▼
  Chrome / Chrome Canary
        │  per-tab CDPSession
        ▼
  domains: console · screenshot · network · ui

Chrome is spawned as a child process. Argus listens to its stderr for the DevTools listening on ws://... line to get the exact WebSocket URL, then connects. Each tab gets its own CDPSession (multiplexed over a single WebSocket connection) with independent domain state.

Development

npm run dev       # start with tsx (no build step)
npm run build     # compile to dist/
npm run typecheck # type-check without emitting

Chrome profile data is stored at ~/.argus/chrome-profile so Chrome doesn't reinitialise on every restart.

Contributing

Contributions are welcome. Argus is an active exploration project, so there's plenty of room to improve.

Before opening a PR:

1. Fork the repo and create a branch from main
2. Run npm run typecheck — PRs must pass type checking
3. Test your changes against a live browser session
4. Keep commits focused; one logical change per PR

Good areas to contribute:

• New CDP domain wrappers (e.g. Performance, Accessibility)
• Additional skills / slash commands
• Bug reports with reproduction steps
• Documentation improvements

Open an issue first for large changes so we can align on approach before you invest time in implementation.

License

MIT