AI-friendly debugging for web applications. Enables LLM agents to inspect, interact with, and control web apps via WebSocket.
npm install -g debug-bridge-clinpm install debug-bridge-browser// src/debug-bridge.ts
import { createDebugBridge } from 'debug-bridge-browser';
if (import.meta.env.DEV) {
const params = new URLSearchParams(window.location.search);
const sessionId = params.get('session') || 'debug';
const port = params.get('port') || '4000';
const bridge = createDebugBridge({
url: `ws://localhost:${port}/debug?role=app&sessionId=${sessionId}`,
sessionId,
appName: 'My App',
});
bridge.connect();
}Import it in your app entry point:
// main.tsx
import './debug-bridge';# Terminal 1: Start the debug server
debug-bridge connect --session myapp
# Terminal 2: Start your app
npm run dev
# Terminal 3: Open browser with debug params
open "http://localhost:5173?session=myapp&port=4000"debug> ui # Get UI tree (interactive elements)
debug> find login # Search for elements matching "login"
debug> click button-abc123 # Click element by stableId
debug> type input-xyz "hello" # Type text into input
debug> screenshot # Capture viewport
debug> state # Get app state (cookies, localStorage, etc.)
debug> eval document.title # Execute JavaScript
debug> help # Show all commands
| Package | Description | Install |
|---|---|---|
debug-bridge-cli |
CLI with WebSocket server | npm install -g debug-bridge-cli |
debug-bridge-browser |
Browser SDK | npm install debug-bridge-browser |
debug-bridge-types |
TypeScript types | npm install debug-bridge-types |
┌─────────────────┐ WebSocket ┌─────────────────┐
│ Your Web App │◄──────────────────►│ Debug Bridge │
│ (browser SDK) │ │ Server │
└─────────────────┘ └────────┬────────┘
│
┌────────▼────────┐
│ CLI / Agent │
│ (sends cmds) │
└─────────────────┘
- Browser SDK connects to the Debug Bridge server via WebSocket
- Server routes messages between your app and the CLI/agent
- CLI/Agent sends commands (click, type, screenshot) and receives telemetry
const bridge = createDebugBridge({
// Required
url: 'ws://localhost:4000/debug?role=app&sessionId=myapp',
sessionId: 'myapp',
// Optional
appName: 'My App',
appVersion: '1.0.0',
enableEval: false, // Enable JavaScript execution (security risk)
enableDomSnapshot: true, // Send DOM snapshots
enableDomMutations: true, // Track DOM changes
enableUiTree: true, // Build interactive element tree
enableConsole: true, // Forward console logs
enableErrors: true, // Forward errors
// Custom state provider (for auth, cart, etc.)
getCustomState: () => ({
user: { id: '123', name: 'John' },
cart: { items: 3 },
}),
// Custom stable ID generator for elements
getStableId: (el) => el.getAttribute('data-testid'),
// Callbacks
onConnect: () => console.log('Connected'),
onDisconnect: () => console.log('Disconnected'),
onError: (err) => console.error(err),
});| Command | Description |
|---|---|
ui / tree |
Get interactive UI elements |
find <query> |
Search cached UI tree |
click <id> |
Click element by stableId |
type <id> <text> |
Type text into element |
eval <code> / js |
Execute JavaScript |
snapshot / dom |
Get full DOM HTML |
screenshot / ss |
Capture viewport |
state [scope] |
Get application state |
navigate <url> / go |
Navigate to URL |
focus <id> |
Focus an element |
scroll <x> <y> |
Scroll to position |
clear |
Clear console |
help / ? |
Show help |
Debug Bridge includes a skill/plugin system for seamless integration with AI coding assistants.
Method 1: From GitHub Marketplace (Recommended)
# 1. Add the agent-bridge marketplace
/plugin marketplace add stevengonsalvez/agent-bridge
# 2. Install the debug-bridge plugin
/plugin install debug-bridge@agent-bridge-marketplaceMethod 2: Local Development/Testing
# Use during development or testing
claude --plugin-dir /path/to/agent-bridgeMethod 3: Manual Installation
# Clone and manually copy
git clone https://github.com/stevengonsalvez/agent-bridge.git
cp -r agent-bridge/.claude-plugin ~/.claude/plugins/debug-bridge
cp -r agent-bridge/skills ~/.claude/plugins/debug-bridge/After installation, trigger the skill by saying:
- "Debug the app"
- "Inspect the UI"
- "Take a screenshot of the page"
- "Click the login button"
- "Automate this workflow"
cp -r skills/debug-bridge ~/.cursor/skills/cp -r skills/debug-bridge ~/.codex/skills/cp -r skills/debug-bridge .github/skills/See skills/debug-bridge/SKILL.md for complete documentation including:
- All available commands with parameters
- Error handling and recovery patterns
- Workflow examples (login, form filling, etc.)
- Troubleshooting guide
For direct programmatic control, connect via WebSocket:
const ws = new WebSocket('ws://localhost:4000/debug?role=agent&sessionId=myapp');
// Get UI tree
ws.send(JSON.stringify({
type: 'request_ui_tree',
requestId: '1',
protocolVersion: 1,
sessionId: 'myapp',
timestamp: Date.now()
}));
// Click element
ws.send(JSON.stringify({
type: 'click',
target: { stableId: 'login-button' },
requestId: '2',
protocolVersion: 1,
sessionId: 'myapp',
timestamp: Date.now()
}));
// Type text with options
ws.send(JSON.stringify({
type: 'type',
target: { stableId: 'email-input' },
text: 'user@example.com',
options: { clear: true, pressEnter: false },
requestId: '3',
protocolVersion: 1,
sessionId: 'myapp',
timestamp: Date.now()
}));
// Take screenshot
ws.send(JSON.stringify({
type: 'request_screenshot',
fullPage: true,
requestId: '4',
protocolVersion: 1,
sessionId: 'myapp',
timestamp: Date.now()
}));| Command | Description | Key Parameters |
|---|---|---|
request_ui_tree |
Get interactive elements | - |
click |
Click element | target: { stableId?, selector?, text? } |
type |
Type text | target, text, options: { clear?, delay?, pressEnter? } |
hover |
Hover over element | target |
select |
Select dropdown option | target, value?, label?, index? |
focus |
Focus element | target |
scroll |
Scroll page/element | target?, x?, y? |
navigate |
Go to URL | url |
evaluate |
Execute JavaScript | code |
request_screenshot |
Capture viewport | selector?, fullPage? |
request_state |
Get cookies/localStorage | scope? |
request_dom_snapshot |
Get full HTML | - |
Commands return structured error responses:
{
"type": "command_result",
"success": false,
"error": {
"code": "TARGET_NOT_FOUND",
"message": "Element not found"
}
}Error codes: TARGET_NOT_FOUND, TARGET_NOT_VISIBLE, TARGET_DISABLED, TIMEOUT, EVAL_DISABLED, EVAL_ERROR, NAVIGATION_FAILED, INVALID_COMMAND
# Install dependencies
pnpm install
# Build all packages
pnpm run build
# Run in development mode
pnpm run devDebug Bridge uses GitHub as a plugin marketplace. There's no central registry - your GitHub repository acts as the distribution source.
Publishing Flow:
-
Create Plugin Structure (already done ✅)
.claude-plugin/ ├── plugin.json # Plugin metadata └── marketplace.json # Marketplace catalog skills/ └── debug-bridge/ # Skill implementation -
Push to GitHub
git add .claude-plugin/ skills/ git commit -m "feat: add Claude Code plugin" git push origin main -
Users Install
# Add your marketplace /plugin marketplace add stevengonsalvez/agent-bridge # Install the plugin /plugin install debug-bridge@agent-bridge-marketplace
- Use semantic versioning in
.claude-plugin/plugin.json - Update version for each release:
{ "version": "0.2.0" // Update this } - Tag releases in Git:
git tag v0.2.0 git push origin v0.2.0
- No review process by Anthropic
- You control the release cycle
- Users pull updates when they reinstall
| Method | Use Case | Installation |
|---|---|---|
| GitHub Marketplace | Public distribution | /plugin marketplace add owner/repo |
| Local Development | Testing, development | claude --plugin-dir ./path |
| Manual Copy | Team sharing, private use | Copy to ~/.claude/plugins/ |
MIT