Dev workflowDeveloper workflow
Local Debugging
How to inspect userscripts, UI iframes, startup failures, server RPC logs, and extension-side SDK messages.
Core Commands
| Command | Purpose |
|---|---|
pnpm run dev | Run the Next app server on port 3000. |
pnpm run ext:dev | Run WXT extension watch mode. |
pnpm run typecheck | Validate TypeScript for the platform app. |
pnpm run log:watch | Tail extension logs. |
curl -s -X POST localhost:3101/reload | Trigger local extension runtime reload when native reload server is running. |
Browser Inspection
- 1Use CDPProject debugging uses Chrome DevTools Protocol on
localhost:9222, not browser MCP tools. - 2Inspect extension pagesOpen the app-shell, dashboard, offscreen document, and service worker targets from CDP.
- 3Inspect userscriptsOpen the target web page and check the USER_SCRIPT world logs/errors.
- 4Correlate server logsServer API responses include request ids; match them with structured JSON logs from the app server.
Common Failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Userscript does not run | Chrome Allow User Scripts disabled or match pattern mismatch | Enable the toggle and verify manifest.userscripts[].matches. |
includeCookies request rejected | Missing host_permissions | Add a narrow Chrome match pattern to the manifest. |
| UI SDK call hangs | Sandbox bridge or app-shell message routing failed | Inspect the app-shell iframe and background service worker logs. |
RPC returns { error, code, requestId } | Server function threw or route failed | Check the request id in server logs. |
window.open opens blank page | USER_SCRIPT world has isolated window object | Use airglow.openWindow. |