{
  "markdown": "# agnt\n\n**Give your AI coding agent browser superpowers.**\n\n[![Go Version](https://img.shields.io/badge/Go-1.24.2-blue.svg)](https://go.dev/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n[![npm](https://img.shields.io/npm/v/@standardbeagle/agnt)](https://www.npmjs.com/package/@standardbeagle/agnt)\n[![PyPI](https://img.shields.io/pypi/v/agnt)](https://pypi.org/project/agnt/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## What is agnt?\n\n**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.\n\nWhen you're in the flow with Claude Code, Cursor, or other AI coding tools, agnt lets your agent:\n\n- **See what you see** - Screenshots, DOM inspection, and visual debugging\n- **Hear from you directly** - Send messages from the browser to your agent\n- **Sketch ideas together** - Draw wireframes directly on your UI\n- **Debug in real-time** - Capture errors, network traffic, and performance metrics\n- **Test on any device** - Tunnel to phones and BrowserStack with full instrumentation\n- **Extend its thinking window** - Structured data uses fewer tokens than your descriptions\n\n## Demo\n\n![A submit button half off-screen: three rounds of blind terminal automation fail, then agnt fixes it in one pass](assets/vhs-spiral-demo.webp)\n\n*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](https://dev.standardbeagle.com/agnt/demos/vhs-spiral) (1:40).*\n\n![Sketch Demo](assets/sketch-demo.webp)\n\n*Draw wireframes directly on your running app, then send them to your AI agent*\n\n## The Vision: Extending Your Agent's Capabilities\n\nTraditional AI coding assistants are blind to what's happening in the browser. They can write code, but they can't:\n\n- See the visual result of their changes\n- Know when JavaScript errors occur\n- Understand layout issues you're experiencing\n- Receive feedback without you typing it out\n\n**agnt changes this.** It creates a bidirectional channel between your browser and your AI agent:\n\n```\n┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐\n│   Your Browser  │ ←──► │      agnt       │ ←──► │   AI Agent      │\n│                 │      │                 │      │                 │\n│  - See changes  │      │  - Proxy traffic│      │  - Receives     │\n│  - Send notes   │      │  - Capture errors│     │    context      │\n│  - Draw sketches│      │  - Inject tools │      │  - Acts on      │\n│  - Click to log │      │  - Route messages│     │    feedback     │\n└─────────────────┘      └─────────────────┘      └─────────────────┘\n```\n\n## Quick Start\n\n### Installation\n\n**npm** (recommended):\n```bash\nnpm install -g @standardbeagle/agnt\n```\n\n**pip/uv**:\n```bash\npip install agnt\n# or\nuv pip install agnt\n```\n\n**From source**:\n```bash\ngit clone https://github.com/standardbeagle/agnt.git\ncd agnt\nmake build && make install-local\n```\n\n### As MCP Server (Claude Code, Cursor, etc.)\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"agnt\": {\n      \"command\": \"agnt\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr install as a Claude Code plugin:\n```bash\n/plugin marketplace add standardbeagle/agnt\n/plugin install agnt@agnt\n```\n\n**One-shot: `agnt skills`** — install the agnt agent skills and register the\nMCP server in a single command. It uses [Vercel's open skills CLI](https://github.com/vercel-labs/skills)\nto fetch the skills, then wires up MCP:\n\n```bash\nagnt skills                 # install for Claude Code + register the MCP server\nagnt skills --agent cursor  # install the skills for a different agent\n```\n\nUnder the hood it runs `npx -y skills add standardbeagle-tools/agnt --all -a\nclaude-code`, then `claude mcp add agnt -s user -- agnt mcp` (for other agents\nit prints the MCP config to add). Requires Node.js (`npx`) on PATH.\n\n### As PTY Wrapper (Enhanced Terminal)\n\nWrap your AI tool for overlay features:\n\n```bash\nagnt run claude --dangerously-skip-permissions\nagnt run cursor\nagnt run aider\n```\n\nThis adds a terminal overlay menu (Ctrl+P) and enables the browser-to-terminal message bridge.\n\n### First-Run Setup (auto-configures a new project)\n\nThe first time you run `agnt run claude` in a project that has no `.agnt.kdl`,\nagnt drives a one-time **setup run** before your coding session:\n\n```bash\ncd my-new-project        # no .agnt.kdl yet\nagnt run claude\n```\n\nMost projects never reach the setup phase: agnt first tries a deterministic\n**auto-config** and writes `.agnt.kdl` itself when the project shape is\nunambiguous. Recognised out of the box:\n\n| Shape | Marker | Dev script and proxy |\n|---|---|---|\n| Node web app | `package.json` with a `dev`/`start` script | that script, proxy via URL detection |\n| Go (Wails) | `wails.json` | `wails dev` |\n| .NET web project | `*.csproj` with the Web SDK at the root, or under `src/*` / `*/` | `dotnet watch run` (per project, port from `launchSettings.json`) |\n| docker-compose | `compose.yaml` / `docker-compose.yml` | `docker compose up`, one proxy per service that publishes a host port |\n| Procfile | `Procfile.dev` / `Procfile` | one script per entry, proxy on `web` |\n| Django | `manage.py` | `python manage.py runserver` (8000) |\n| Rails | `bin/rails` | `bin/dev` or `bin/rails server` (3000) |\n| Laravel | `artisan` | `composer run dev` or `php artisan serve` (8000) |\n| Phoenix | `mix.exs` with `:phoenix` | `mix phx.server` (4000) |\n| Hugo / Jekyll / mkdocs | `hugo.toml` + `content/`, `_config.yml` + Gemfile, `mkdocs.yml` | `hugo server` (1313), `bundle exec jekyll serve` (4000), `mkdocs serve` (8000) |\n| Static site | `index.html` at the root | stdlib file server (8000) |\n\nDetection accumulates: a .NET solution with a compose file gets dotnet\ntest/build plus the compose topology. Test, lint, and build commands for Go,\nNode, Python, Ruby, PHP, Elixir, and .NET are registered as on-demand scripts.\nKnown ports are written as `fallback-port` so the proxy exists before the first\nrequest. Edit the generated file freely; changes apply live.\n\nOnly when auto-config cannot decide does the setup phase run:\n\n1. **Setup phase** — Claude launches in setup mode and configures the project:\n   it detects the stack, registers your dev-server\n   script(s) and a reverse proxy, and writes a `.agnt.kdl`. If the\n   `agnt:setup-project` skill isn't installed, Claude tells you the exact\n   install step (`/plugin marketplace add standardbeagle/agnt` then\n   `/plugin install agnt`).\n2. **Relaunch** — when setup exits, agnt relaunches Claude into a normal coding\n   session with autostart enabled, replaying your original arguments. Your dev\n   servers and proxy come up automatically.\n\n```bash\n# Pass a task through — it's replayed verbatim into the relaunched session:\nagnt run claude -- \"add a /healthz endpoint\"\n```\n\nIf you decline setup (no `.agnt.kdl` gets written), agnt records a timestamped\nmarker and won't nudge again until the re-nudge window elapses (default 7 days,\nconfigurable via `setup { renudge-ttl-days 7 }` in `.agnt.kdl`). A successful\nsetup is remembered permanently.\n\nSetup also works for other agents — each gets install instructions tailored to\nits own skill/command mechanism (see\n[docs/agent-support-matrix.md](docs/agent-support-matrix.md)).\n\n### `agnt init` — configure without launching a session\n\nPrefer to set the project up on its own? `agnt init` runs only the setup phase\n(no relaunch) and exits once `.agnt.kdl` is written:\n\n```bash\nagnt init            # configure with claude\nagnt init gemini     # configure with a different agent\n```\n\nA successful `agnt init` records the permanent marker too, so a later\n`agnt run` skips straight to the coding session.\n\n### Channel Mode (Beta — Claude Code only)\n\n> **Beta / Experimental**: Channel mode requires a forked MCP SDK and a development flag in Claude Code. Behavior and schema may change.\n\nClaude 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](CLAUDE.md#channel-mode-claude-code-only) for full schema, event format, and the `channel_reply` tool for sending messages back to the browser overlay.\n\n## Core Features\n\n### 1. Browser Superpowers\n\nStart a proxy and your agent gains eyes into the browser:\n\n```\nproxy {action: \"start\", id: \"app\", target_url: \"http://localhost:3000\"}\n```\n\nNow your agent can:\n```javascript\n// Take screenshots\nproxy {action: \"exec\", id: \"app\", code: \"__devtool.screenshot('current-state')\"}\n\n// Inspect any element\nproxy {action: \"exec\", id: \"app\", code: \"__devtool.inspect('#submit-button')\"}\n\n// Audit accessibility\nproxy {action: \"exec\", id: \"app\", code: \"__devtool.auditAccessibility()\"}\n\n// Check what the user clicked\nproxy {action: \"exec\", id: \"app\", code: \"__devtool.interactions.getLastClickContext()\"}\n```\n\n### 2. The Floating Indicator\n\nEvery proxied page gets a small floating bug icon. Click it to:\n\n- **Send messages** directly to your AI agent\n- **Take screenshots** of specific areas\n- **Select elements** to log their details\n- **Open sketch mode** for wireframing\n\nNo more alt-tabbing to describe what you see - just click and send.\n\n### 3. Sketch Mode\n\nPress the sketch button and draw directly on your UI:\n\n- Rectangles, circles, arrows, and freehand drawing\n- Wireframe elements: buttons, inputs, sticky notes\n- Save and send to your agent with one click\n\nPerfect for saying \"I want a button here\" or \"this layout is wrong\" without typing a word.\n\n### 4. Real-Time Error Capture\n\nJavaScript errors are automatically captured and available to your agent:\n\n```\nproxylog {proxy_id: \"app\", types: [\"error\"]}\n→ {message: \"TypeError: Cannot read property 'map' of undefined\",\n   stack: \"at ProductList (products.js:42)\",\n   timestamp: \"...\"}\n```\n\nYour agent sees errors as they happen, not when you remember to mention them.\n\n### 5. Extending the Thinking Window\n\nStructured data consumes fewer tokens than natural language descriptions:\n\n- **Error summaries** - `proxylog {types: [\"error\"]}` vs. \"I'm seeing a TypeError on line 42 that says...\"\n- **Click context** - `interactions.getLastClickContext()` vs. \"I clicked the blue button in the header...\"\n- **DOM state** - `inspect('#element')` vs. \"there's a div with some nested spans and...\"\n- **Consolidated stack traces** - Pre-processed React error walls into actionable summaries\n- **Status at a glance** - Structured JSON your agent can parse efficiently\n\nInstead of dumping 100 lines of nested React errors into the context, agnt consolidates verbose output into concise, actionable data.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `detect` | Auto-detect project type and available scripts |\n| `run` | Execute scripts or commands (background/foreground) |\n| `proc` | Manage processes: status, output, stop, list |\n| `proxy` | Reverse proxy: start, stop, exec, status |\n| `proxylog` | Query logs: http, error, screenshot, sketch, panel_message |\n| `currentpage` | View active page sessions with grouped resources |\n| `get_incidents` | Authoritative pull from the always-active incident inbox |\n| `responsive_audit` | Responsive audit across viewport sizes (layout/overflow/a11y) |\n| `api_audit` | API-efficiency audit: waterfall, N+1, duplicate, chatty-load |\n| `loading_audit` | Loading-UX audit: spinner cascade + concurrent fragmentation |\n| `snapshot` | Visual regression: baseline/compare screenshots |\n| `tunnel` | Tunnel management: cloudflare/ngrok for mobile testing |\n| `daemon` | Manage background daemon service |\n| `watch` | Stream daemon events via `agnt monitor` |\n| `channel_reply` | Send messages to developer's browser overlay (channel mode only) |\n\n## Browser API (50+ Functions)\n\nThe proxy injects `window.__devtool` with powerful diagnostics:\n\n**Element Inspection**\n```javascript\n__devtool.inspect('#element')     // Full element analysis\n__devtool.getPosition('#element') // Bounding box and position\n__devtool.isVisible('#element')   // Visibility check\n```\n\n**Visual Debugging**\n```javascript\n__devtool.highlight('.items')           // Highlight elements\n__devtool.mutations.highlightRecent()   // Show recent DOM changes\n__devtool.screenshot('name')            // Capture screenshot\n```\n\n**Accessibility**\n```javascript\n__devtool.auditAccessibility()    // Full a11y audit with score\n__devtool.getContrast('#text')    // Color contrast check\n__devtool.getTabOrder()           // Tab navigation order\n```\n\n**Interactions**\n```javascript\n__devtool.interactions.getLastClick()        // Last click details\n__devtool.interactions.getLastClickContext() // Full click context\n__devtool.selectElement()                    // Interactive picker\n```\n\n**Sketch Mode**\n```javascript\n__devtool.sketch.open()    // Enter sketch mode\n__devtool.sketch.save()    // Save and send to agent\n__devtool.sketch.toJSON()  // Export sketch data\n```\n\n**Responsive Mode**\n```javascript\n__devtool.responsive.open()       // Open the interactive width workbench\n__devtool.responsive.setWidth(414) // Drive the frame to a width (320–1920)\n__devtool.responsive.getState()    // Read current width + detected layout shifts\n```\n\n**Scored Audits**\n```javascript\n__devtool.auditAll()  // 8 weighted audits: dom, css, perf, security, seo,\n                      // a11y, API efficiency, loading/spinner → overall grade\n```\n\n## Configuration\n\nCreate `.agnt.kdl` in your project root to auto-start scripts, proxies, and configure browser notifications:\n\n```kdl\n// Scripts to run via daemon process manager\nscripts {\n    dev {\n        run \"npm run dev\"           // Shell command (recommended)\n        autostart true\n        url-matchers \"(Local|Network):\\\\s*{url}\"\n    }\n\n    api {\n        command \"go\"                // Or use command + args\n        args \"run\" \"./cmd/server\"\n        autostart true\n        env {\n            GIN_MODE \"debug\"\n        }\n        cwd \"./backend\"\n    }\n}\n\n// Reverse proxies with traffic logging\nproxies {\n    frontend {\n        script \"dev\"               // Link to script for URL auto-detection\n    }\n\n    backend {\n        target \"http://localhost:8080\"\n        autostart true\n        max-log-size 2000\n    }\n}\n\n// Browser notifications when AI responds\nhooks {\n    on-response {\n        toast true                 // Show toast notification\n        indicator true             // Flash bug indicator\n        sound false                // Play notification sound\n    }\n}\n\n// Toast appearance\ntoast {\n    duration 4000\n    position \"bottom-right\"        // top-right, top-left, bottom-right, bottom-left\n    max-visible 3\n}\n```\n\nRun `/setup-project` in Claude Code to interactively generate this configuration.\n\n**Framework-specific URL matchers:**\n\n| Framework | url-matchers |\n|-----------|-------------|\n| Next.js / Vite / React | `\"(Local\\|Network):\\\\s*{url}\"` |\n| Wails | `\"DevServer URL:\\\\s*{url}\"` |\n| Astro | `\"Local\\\\s+{url}\"` |\n| Jekyll | `\"Server address:\\\\s*{url}\"` |\n| Hugo | `\"Web Server.*available at {url}\"` |\n\n## Architecture\n\nagnt uses a daemon architecture for persistent state:\n\n```\n┌─────────────────────┐       ┌─────────────────────────────────────┐\n│  AI Agent           │       │              agnt                   │\n│  (Claude Code, etc.)│◄─────►│                                     │\n│                     │ MCP   │  ┌────────────────┐                 │\n└─────────────────────┘       │  │  MCP Server    │                 │\n                              │  └───────┬────────┘                 │\n                              │          │ socket                   │\n                              │          ▼                          │\n┌─────────────────────┐       │  ┌────────────────────────────────┐ │\n│  Browser            │◄──────┼──│        Daemon                  │ │\n│                     │ proxy │  │  ProcessManager │ ProxyManager │ │\n│  __devtool API      │       │  └────────────────────────────────┘ │\n│  Floating Indicator │       └─────────────────────────────────────┘\n│  Sketch Mode        │\n└─────────────────────┘\n```\n\n**Key design decisions:**\n- Lock-free concurrency with `sync.Map` and atomics\n- Bounded memory with ring buffers\n- Processes and proxies survive client disconnections\n- Zero-dependency frontend JavaScript\n\n## Documentation\n\n**[Full Documentation →](https://dev.standardbeagle.com/agnt/)**\n\n```bash\n# Run docs locally\ncd docs-site\nnpm install && npm start\n```\n\n## Use Cases\n\n- **Vibe coding** - Stay in flow while your agent sees everything\n- **Visual debugging** - Show don't tell - sketch what's wrong\n- **Mobile testing** - Tunnel your dev server for real device testing with Cloudflare/ngrok + BrowserStack integration\n- **Accessibility testing** - Automated a11y audits during development\n- **Error tracking** - Catch frontend errors before users do\n- **UI reviews** - Annotate designs directly on the live app\n- **Remote collaboration** - Share visual context with your agent\n\n## Requirements\n\n- Node.js 18+ or Go 1.24+\n- MCP-compatible AI assistant\n\n## Migrating from devtool-mcp\n\nagnt is the new name for devtool-mcp. Existing users:\n\n```bash\n# npm\nnpm uninstall -g @standardbeagle/devtool-mcp\nnpm install -g @standardbeagle/agnt\n\n# pip\npip uninstall devtool-mcp\npip install agnt\n```\n\nUpdate your MCP config to use `agnt` command with `[\"mcp\"]` args.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! See the [documentation](https://dev.standardbeagle.com/agnt/) for architecture details.\n",
  "bytes": 17693,
  "sha": "4caa0d4cbdd9d643a8254c2b04edbcea8d9f35b47af12b561b93ea3ce8163a1c",
  "repo_slug": "standardbeagle/devtool-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_standardbeagle_devtool_mcp_73385f7e/readme"
}