| name | electron-cdp-debugging |
| description | Use when discussing, debugging, visually comparing, or verifying this project's Electron desktop app, especially with npm run desktop:dev, Chrome DevTools Protocol, CDP, remote debugging port 9222, uploaded screenshots, or desktop UI changes. |
Electron CDP Debugging
Overview
Use the development Electron app as the source of truth. Start it when needed, inspect it through CDP, compare against the user's uploaded screenshot before editing, and verify the final UI through CDP interaction.
Workflow
- Check whether the development Electron app is already running and exposing CDP on
127.0.0.1:9222.
- If it is not running, start it with
npm run desktop:dev and keep the process alive while working.
- Read the console logs for the remote debugging line, for example:
Electron remote debugging listening on port 9222
DevTools listening on ws://127.0.0.1:9222/devtools/browser/...
- Connect to the CDP endpoint at
http://127.0.0.1:9222.
- Use the live CDP page state, screenshots, accessibility tree, DOM, console errors, and network state to identify the real target screen.
- If the user uploaded a screenshot, compare it with the current Electron window before changing code. Confirm the target route, panel, dialog, or component from the live app rather than guessing from file names.
- Discuss blockers or ambiguous product questions using what CDP shows: current screen, visible text, element states, console output, and reproduction steps.
- For final validation, interact with the Electron app through CDP and confirm the changed behavior or visual result in the live window.
Commands
Start the app when no dev instance is available:
npm run desktop:dev
Check the CDP endpoint:
curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list
Connect with any available CDP-capable browser tool. If Libretto is being used, connect like this:
npx libretto connect http://127.0.0.1:9222 --session electron-cdp
npx libretto snapshot --session electron-cdp
Rules
- Do not claim the Electron app was verified unless CDP inspection or interaction confirmed it.
- Do not rely only on static code inspection when the request concerns visible desktop behavior.
- Preserve a running
npm run desktop:dev session until debugging or verification is complete.
- Use the port printed in logs if it differs from
9222.
- Treat an uploaded screenshot as the target visual reference and the CDP app state as the runnable truth.
Common Mistakes
| Mistake | Correction |
|---|
| Editing from component names only | First identify the live route and element through CDP |
Assuming port 9222 without checking logs | Read the desktop:dev output and use the actual port |
| Verifying with tests only | Also verify visible desktop behavior through CDP |
| Discussing vague UI state | Cite the current CDP-observed screen, text, and console state |
