Playwright MCP Live Debugging

Connect to a running VoiceTree Electron app for live debugging via browser automation.

Quick Start (3 steps)

1. Start Electron in debug mode

cd webapp && npm run electron:debug

This starts Electron with CDP enabled on port 9222 and automatically calls prettySetupAppForElectronDebugging() once the renderer is ready — loading the example_small project and spawning 3 debug terminals.

Run with a bash timeout (e.g. 30s) since this is a long-running dev server.

2. Verify CDP is ready

curl -s http://localhost:9222/json/version

Should return JSON with "Browser": "Chrome/...".

3. Go straight to inspecting — do NOT navigate

The app is already loaded with the project and debug terminals. Do not run browser_navigate or page.goto() — this would force-refresh and destroy the loaded state. Instead, jump directly to:

// browser_evaluate — check cytoscape nodes
const cy = window.cytoscapeInstance;
JSON.stringify({ nodeCount: cy.nodes().length, edgeCount: cy.edges().length });

Use browser_snapshot or browser_take_screenshot for visual inspection.

Opening a specific project (optional)

If you need a specific project instead of the test fixture:

await window.electronAPI.main.initializeProject('/path/to/folder');

Available Tools

Tool	Purpose
browser_snapshot	Get accessibility tree of current page
browser_click	Click elements by ref
browser_hover	Hover over elements
browser_type	Type into inputs
browser_evaluate	Run JavaScript in page context
browser_tabs	Switch between tabs
browser_wait_for	Wait for text/elements
browser_take_screenshot	Capture visual screenshot

Accessing App APIs

The app exposes window.electronAPI with useful methods:

// Via browser_evaluate
Object.keys(window.electronAPI.main)

// Key methods:
window.electronAPI.main.prettySetupAppForElectronDebugging()  // Spawn debug terminals
window.electronAPI.main.initializeProject(path)  // Open a folder
window.electronAPI.main.getGraph()               // Get graph data
window.electronAPI.main.getNode(id)              // Get node details
window.electronAPI.main.loadSettings()           // App settings

Cytoscape Instance

Access the graph directly via window.cytoscapeInstance:

// Get all nodes in the graph
const cy = window.cytoscapeInstance;
cy.nodes().map(n => ({ id: n.id(), isContext: n.data('isContextNode') }));

// Get node count
cy.nodes().length;

CRITICAL: Do NOT navigate or refresh the app

electron:debug automatically loads the project and spawns debug terminals. The app is already at the right page when CDP is ready. Do NOT:

• Run browser_navigate / page.goto() — this will force-refresh the app and lose all loaded state
• Hit /json in the browser — same problem

Instead, go straight to browser_evaluate to inspect the page state (e.g. query cytoscape nodes, check DOM elements). Use browser_snapshot or browser_take_screenshot for visual inspection.

CRITICAL: Be surgical when killing Electron processes

VoiceTree itself runs as an Electron process. A blanket pkill -f electron or kill -9 on all Electron PIDs will kill your own host app. To kill only the debug Electron:

# Find ONLY the process listening on port 9222
lsof -i :9222 -sTCP:LISTEN
# Then kill that specific PID
kill <pid>

Never use pkill -f electron or kill Electron PIDs found via lsof -i :9222 without the -sTCP:LISTEN filter — connected clients (including your own app) also show up.

Troubleshooting

Issue	Solution
Connection refused	Ensure Electron started with npm run electron:debug
Timeout on first connect	Retry - first connection can be slow
Wrong tab selected	browser_tabs action=select index=1
Native dialog opened	Use JavaScript APIs instead - native dialogs can't be automated
Old Electron still running	lsof -i :9222 -sTCP:LISTEN then kill <that-pid>

Architecture

Claude Code → @playwright/mcp --cdp-endpoint http://localhost:9222 → CDP → Electron App → VoiceTree Webapp

Notes

• CDP only accesses renderer process, not Electron main process
• Hot reload works - no restart needed on code changes
• Native file dialogs cannot be automated - use electronAPI.main.initializeProject() instead
• Only one debug session at a time (port 9222 hardcoded)