DevTool MCP

agnt

Give your AI coding agent browser superpowers.

[Go Version] [MCP] [npm] [PyPI] [License]

What is agnt?

agnt is a new kind of tool designed for the age of AI-assisted development. It acts as a bridge between your AI coding agent and the browser, extending what's possible during vibe coding sessions.

When you're in the flow with Claude Code, Cursor, or other AI coding tools, agnt lets your agent:

• See what you see - Screenshots, DOM inspection, and visual debugging
• Hear from you directly - Send messages from the browser to your agent
• Sketch ideas together - Draw wireframes directly on your UI
• Debug in real-time - Capture errors, network traffic, and performance metrics
• Test on any device - Tunnel to phones and BrowserStack with full instrumentation
• Extend its thinking window - Structured data uses fewer tokens than your descriptions

Demo

[A submit button half off-screen: three rounds of blind terminal automation fail, then agnt fixes it in one pass]

Three rounds of blind terminal automation can't fix a button that's half off-screen. One pass with eyes on the live page can — full demo (1:40).

[Sketch Demo]

Draw wireframes directly on your running app, then send them to your AI agent

The Vision: Extending Your Agent's Capabilities

Traditional AI coding assistants are blind to what's happening in the browser. They can write code, but they can't:

• See the visual result of their changes
• Know when JavaScript errors occur
• Understand layout issues you're experiencing
• Receive feedback without you typing it out

agnt changes this. It creates a bidirectional channel between your browser and your AI agent:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐│   Your Browser  │ ←──► │      agnt       │ ←──► │   AI Agent      ││                 │      │                 │      │                 ││  - See changes  │      │  - Proxy traffic│      │  - Receives     ││  - Send notes   │      │  - Capture errors│     │    context      ││  - Draw sketches│      │  - Inject tools │      │  - Acts on      ││  - Click to log │      │  - Route messages│     │    feedback     │└─────────────────┘      └─────────────────┘      └─────────────────┘

Quick Start

Installation

npm (recommended):

npm install -g @standardbeagle/agnt

pip/uv:

pip install agnt# oruv pip install agnt

From source:

git clone https://github.com/standardbeagle/agnt.gitcd agntmake build && make install-local

As MCP Server (Claude Code, Cursor, etc.)

Add to your MCP configuration:

{  "mcpServers": {    "agnt": {      "command": "agnt",      "args": ["mcp"]    }  }}

Or install as a Claude Code plugin:

/plugin marketplace add standardbeagle/agnt/plugin install agnt@agnt

One-shot: agnt skills — install the agnt agent skills and register the MCP server in a single command. It uses Vercel's open skills CLI to fetch the skills, then wires up MCP:

agnt skills                 # install for Claude Code + register the MCP serveragnt skills --agent cursor  # install the skills for a different agent

Under the hood it runs npx -y skills add standardbeagle-tools/agnt --all -a claude-code, then claude mcp add agnt -s user -- agnt mcp (for other agents it prints the MCP config to add). Requires Node.js (npx) on PATH.

As PTY Wrapper (Enhanced Terminal)

Wrap your AI tool for overlay features:

agnt run claude --dangerously-skip-permissionsagnt run cursoragnt run aider

This adds a terminal overlay menu (Ctrl+P) and enables the browser-to-terminal message bridge.

First-Run Setup (auto-configures a new project)

The first time you run agnt run claude in a project that has no .agnt.kdl, agnt drives a one-time setup run before your coding session:

cd my-new-project        # no .agnt.kdl yetagnt run claude

Most projects never reach the setup phase: agnt first tries a deterministic auto-config and writes .agnt.kdl itself when the project shape is unambiguous. Recognised out of the box:

Detection accumulates: a .NET solution with a compose file gets dotnet test/build plus the compose topology. Test, lint, and build commands for Go, Node, Python, Ruby, PHP, Elixir, and .NET are registered as on-demand scripts. Known ports are written as fallback-port so the proxy exists before the first request. Edit the generated file freely; changes apply live.

Only when auto-config cannot decide does the setup phase run:

1. Setup phase — Claude launches in setup mode and configures the project: it detects the stack, registers your dev-server script(s) and a reverse proxy, and writes a .agnt.kdl. If the agnt:setup-project skill isn't installed, Claude tells you the exact install step (/plugin marketplace add standardbeagle/agnt then /plugin install agnt).
2. Relaunch — when setup exits, agnt relaunches Claude into a normal coding session with autostart enabled, replaying your original arguments. Your dev servers and proxy come up automatically.

# Pass a task through — it's replayed verbatim into the relaunched session:agnt run claude -- "add a /healthz endpoint"

If you decline setup (no .agnt.kdl gets written), agnt records a timestamped marker and won't nudge again until the re-nudge window elapses (default 7 days, configurable via setup { renudge-ttl-days 7 } in .agnt.kdl). A successful setup is remembered permanently.

Setup also works for other agents — each gets install instructions tailored to its own skill/command mechanism (see docs/agent-support-matrix.md).

agnt init — configure without launching a session

Prefer to set the project up on its own? agnt init runs only the setup phase (no relaunch) and exits once .agnt.kdl is written:

agnt init            # configure with claudeagnt init gemini     # configure with a different agent

A successful agnt init records the permanent marker too, so a later agnt run skips straight to the coding session.

Channel Mode (Beta — Claude Code only)

Beta / Experimental: Channel mode requires a forked MCP SDK and a development flag in Claude Code. Behavior and schema may change.

Claude Code v2.1.80+ can receive real-time browser errors, diagnostics, and user interactions as push events in context -- without the PTY wrapper. Add channel { enabled true } to .agnt.kdl and launch with claude --dangerously-load-development-channels server:agnt. See the Channel Mode section in CLAUDE.md for full schema, event format, and the channel_reply tool for sending messages back to the browser overlay.

Core Features

1. Browser Superpowers

Start a proxy and your agent gains eyes into the browser:

proxy {action: "start", id: "app", target_url: "http://localhost:3000"}

Now your agent can:

// Take screenshotsproxy {action: "exec", id: "app", code: "__devtool.screenshot('current-state')"}
// Inspect any elementproxy {action: "exec", id: "app", code: "__devtool.inspect('#submit-button')"}
// Audit accessibilityproxy {action: "exec", id: "app", code: "__devtool.auditAccessibility()"}
// Check what the user clickedproxy {action: "exec", id: "app", code: "__devtool.interactions.getLastClickContext()"}

2. The Floating Indicator

Every proxied page gets a small floating bug icon. Click it (or press Ctrl+Y) to open the developer panel: a drawer docked on the left that pushes your app aside. Drag its header to detach it into a floating window, drop it on either edge to dock it again, and drag its edge to resize. From the panel you can:

• Send messages directly to your AI agent
• Take screenshots of specific areas
• Select elements to log their details
• Open sketch mode for wireframing

No more alt-tabbing to describe what you see - just click and send.

3. Sketch Mode

Press the sketch button and draw directly on your UI:

• Rectangles, circles, arrows, and freehand drawing
• Wireframe elements: buttons, inputs, sticky notes
• Save and send to your agent with one click

Perfect for saying "I want a button here" or "this layout is wrong" without typing a word.

4. Real-Time Error Capture

JavaScript errors are automatically captured and available to your agent:

proxylog {proxy_id: "app", types: ["error"]}→ {message: "TypeError: Cannot read property 'map' of undefined",   stack: "at ProductList (products.js:42)",   timestamp: "..."}

Your agent sees errors as they happen, not when you remember to mention them.

5. Extending the Thinking Window

Structured data consumes fewer tokens than natural language descriptions:

• Error summaries - proxylog {types: ["error"]} vs. "I'm seeing a TypeError on line 42 that says..."
• Click context - interactions.getLastClickContext() vs. "I clicked the blue button in the header..."
• DOM state - inspect('#element') vs. "there's a div with some nested spans and..."
• Consolidated stack traces - Pre-processed React error walls into actionable summaries
• Status at a glance - Structured JSON your agent can parse efficiently

Instead of dumping 100 lines of nested React errors into the context, agnt consolidates verbose output into concise, actionable data.

6. Sign In as Anyone

Declare test users in .agnt.kdl and agnt serves a dev OIDC issuer on your proxy. Switch between a standard user and an admin from the indicator's persona chip, :as admin in the terminal, or the devauth tool for your agent. No real IdP accounts involved.

[The story app signs in through agnt's dev issuer over the tailnet, then switches from Dev Standard to Dev Admin from the persona chip]

Works over loopback, over your tailnet (bind "tailscale", identity from tailscale whois, served over HTTPS with the node's certificate when the tailnet issues one), and behind a named Cloudflare tunnel with Access verified at the origin. See Dev Sign-in & Protected Sharing.

MCP Tools

Browser API (50+ Functions)

The proxy injects window.__devtool with powerful diagnostics:

Element Inspection

__devtool.inspect('#element')     // Full element analysis__devtool.getPosition('#element') // Bounding box and position__devtool.isVisible('#element')   // Visibility check

Visual Debugging

__devtool.highlight('.items')           // Highlight elements__devtool.mutations.highlightRecent()   // Show recent DOM changes__devtool.screenshot('name')            // Capture screenshot

Accessibility

__devtool.auditAccessibility()    // Full a11y audit with score__devtool.getContrast('#text')    // Color contrast check__devtool.getTabOrder()           // Tab navigation order

Interactions

__devtool.interactions.getLastClick()        // Last click details__devtool.interactions.getLastClickContext() // Full click context__devtool.selectElement()                    // Interactive picker

Sketch Mode

__devtool.sketch.open()    // Enter sketch mode__devtool.sketch.save()    // Save and send to agent__devtool.sketch.toJSON()  // Export sketch data

Responsive Mode

__devtool.responsive.open()       // Open the interactive width workbench__devtool.responsive.setWidth(414) // Drive the frame to a width (320–1920)__devtool.responsive.getState()    // Read current width + detected layout shifts

Scored Audits

__devtool.auditAll()  // 8 weighted audits: dom, css, perf, security, seo,                      // a11y, API efficiency, loading/spinner → overall grade

Configuration

Create .agnt.kdl in your project root to auto-start scripts and proxies:

// Scripts to run via daemon process managerscripts {    dev {        run "npm run dev"           // Shell command (recommended)        autostart true        url-matchers "(Local|Network):\\s*{url}"    }
    api {        command "go"                // Or use command + args        args "run" "./cmd/server"        autostart true        env {            GIN_MODE "debug"        }        cwd "./backend"    }}
// Reverse proxies with traffic loggingproxies {    frontend {        script "dev"               // Link to script for URL auto-detection    }
    backend {        target "http://localhost:8080"        autostart true        max-log-size 2000    }}

Browser-side error/diagnostic delivery to the agent is configured via alerts {}, not a toast/hook block — see docs/configuration.md.

Run /setup-project in Claude Code to interactively generate this configuration.

Framework-specific URL matchers:

Architecture

agnt uses a daemon architecture for persistent state:

┌─────────────────────┐       ┌─────────────────────────────────────┐│  AI Agent           │       │              agnt                   ││  (Claude Code, etc.)│◄─────►│                                     ││                     │ MCP   │  ┌────────────────┐                 │└─────────────────────┘       │  │  MCP Server    │                 │                              │  └───────┬────────┘                 │                              │          │ socket                   │                              │          ▼                          │┌─────────────────────┐       │  ┌────────────────────────────────┐ ││  Browser            │◄──────┼──│        Daemon                  │ ││                     │ proxy │  │  ProcessManager │ ProxyManager │ ││  __devtool API      │       │  └────────────────────────────────┘ ││  Floating Indicator │       └─────────────────────────────────────┘│  Sketch Mode        │└─────────────────────┘

Key design decisions:

• Lock-free concurrency with sync.Map and atomics
• Bounded memory with ring buffers
• Processes and proxies survive client disconnections
• Zero-dependency frontend JavaScript

Documentation

Full Documentation →

# Run docs locallycd docs-sitenpm install && npm start

Use Cases

• Vibe coding - Stay in flow while your agent sees everything
• Visual debugging - Show don't tell - sketch what's wrong
• Mobile testing - Tunnel your dev server for real device testing with Cloudflare/ngrok + BrowserStack integration
• Accessibility testing - Automated a11y audits during development
• Error tracking - Catch frontend errors before users do
• UI reviews - Annotate designs directly on the live app
• Remote collaboration - Share visual context with your agent

Requirements

• Node.js 18+ or Go 1.24+
• MCP-compatible AI assistant

Migrating from devtool-mcp

agnt is the new name for devtool-mcp. Existing users:

# npmnpm uninstall -g @standardbeagle/devtool-mcpnpm install -g @standardbeagle/agnt
# pippip uninstall devtool-mcppip install agnt

Update your MCP config to use agnt command with ["mcp"] args.

License

MIT

Contributing

Contributions welcome! See the documentation for architecture details.