A lightweight Electron app that connects to a remote Chromium-based browser via Chrome DevTools Protocol (CDP), providing a native-like browsing experience with real-time screencast, tab management, and full input forwarding.
- Real-time screencast — JPEG frame stream from the remote browser rendered on a canvas
- Full input forwarding — mouse clicks, movement, scroll, keyboard events; macOS-reserved combos fall through to native handlers
- Tab management — create, close, switch, drag-reorder, and reopen closed tabs
- Pins — hold live tabs; click shows the tab's content, cmd/middle-click opens an independent tab; drag-reorder; edit title/URL
- Notifications — Teams and Outlook (OWA) toast capture via read-only CDP side-channels; bell badge + OS alerts; deep-open exact message from notification
- Arc-like UI — collapsible sidebar, pill-shaped URL bar, shadcn/ui components
- Light / Dark / System theme — with smooth transitions
- Adaptive Viewport — optional mode that eliminates letterbox bars by resizing the remote page to match the canvas
- Navigation history — back/forward buttons reflect actual browser history
- Keyboard shortcuts — see table below
- Configurable — remote CDP host/port via settings drawer, with immediate reconnect on save
- macOS native — hidden title bar with traffic light integration
A Chromium-based browser running with remote debugging enabled:
# Chrome
google-chrome --remote-debugging-port=9222
# Microsoft Edge
msedge --remote-debugging-port=9222
# Chromium
chromium --remote-debugging-port=9222The browser can be on the same machine or accessible over the network (e.g., via SSH tunnel or Tailscale). See Reaching a remote CDP browser through a Tailscale jump host.
git clone https://github.com/duongdev/cdp-browser.git
cd cdp-browser
pnpm installRequires Node 24 (node-linker=hoisted is set in .npmrc).
pnpm devStarts Vite dev server + Electron with hot reload.
pnpm startBuilds the renderer and launches Electron.
pnpm dist # Creates DMG + ZIP
pnpm dist:dir # Creates unpacked app (faster, for testing)Output goes to release/.
pnpm install:local # Build + install CDP Browser.app (strips quarantine)On first launch, configure the remote CDP address via ⌘, (Settings):
- Host: IP or hostname of the machine running the remote browser (default:
localhost) - Port: CDP debugging port (default:
9222)
Settings are persisted in the Electron userData directory.
| Shortcut | Action |
|---|---|
⌘, |
Open Settings |
⌘T |
New tab |
⌘W |
Close current tab |
⌘⇧T |
Reopen last closed tab |
⌃Tab / ⌃⇧Tab |
Next / Previous tab |
⌘1–⌘9 |
Switch to pin/tab by position (pins first, 9 = last) |
⌘L |
Focus address bar |
⌘⌥L |
Copy current URL |
⌘R |
Reload page |
⌘[ / ⌘] |
Back / Forward |
⌘D |
Pin / unpin current tab |
⌘S |
Toggle sidebar |
Esc |
Unfocus address bar |
Trackpad swipe left/right is supported for back/forward navigation.
[CDP Browser] --HTTP--> [Remote Browser :9222/json] (tab list, create, close)
[CDP Browser] --WS----> [Remote Browser WS endpoint] (screencast, input, navigation)
- The app connects to the CDP HTTP API to list and manage tabs.
- When a tab is selected, it opens a WebSocket to that tab's debugger endpoint.
Page.startScreencaststreams JPEG frames drawn to a canvas.- Mouse and keyboard events are mapped and forwarded via
Input.dispatch*methods. - Read-only side-channel sockets attach to notification-capable tabs (Teams, Outlook/OWA) and capture in-app toasts; clicking a notification activates the tab and, for Outlook, deep-opens the exact message via SPA navigation.
- Electron — desktop runtime
- React 19 — UI framework
- Tailwind CSS 4 — styling
- shadcn/ui — component library (radix-nova preset)
- HugeIcons — icon set
- dnd-kit — drag and drop
- Vite — build tool
MIT