Simple Browser

Simple Browser is a tiny Electron shell that launches a Chromium window with remote debugging enabled. It can also launch native Chrome/Chromium instead. Published as an npm binary so you can spin up a clean browser profile from the command line in seconds.

Quick Start

Run once

npx --yes simple-browser@latest

Install globally then run

# Install
npm install --global simple-browser@latest

# Run
simple-browser
# or
browser

When no URL is provided, the browser opens the Chrome DevTools Protocol version endpoint on the remote debugging port.

CLI Usage

simple-browser [OPTIONS] [URL]
simple-browser COMMAND [OPTIONS]

Options

Option	Description
-b, --browser BROWSER	Browser to use: electron (default) or chrome
--remote-debugging-port PORT	Set remote debugging port (highest priority)
--port PORT	Set remote debugging port (alias)
-p PORT	Set remote debugging port (short alias)
--<chromium-switch>[=VALUE]	Pass any switch to Chromium (e.g., --disable-gpu)
-h, --help	Show help message

Commands

Command	Description
start	Start a background process managed by PM2
stop	Stop and remove the PM2-managed process

Examples

# Open a URL in Electron
simple-browser https://example.com

# Open a URL in native Chrome
simple-browser -b chrome https://example.com

# Set a specific remote debugging port
simple-browser --port 9333 https://example.com

# Pass Chromium switches
simple-browser --disable-gpu --proxy-server=http://proxy:8080 https://example.com

# Start as a background process (PM2)
simple-browser start
simple-browser start --port 9333

# Stop a background process
simple-browser stop
simple-browser stop --port 9333

Port Priority

The remote debugging port is resolved in this order:

1. --remote-debugging-port CLI option
2. --port CLI option
3. -p CLI option
4. REMOTE_DEBUGGING_PORT environment variable
5. Auto-find a free port starting at 9222

In-App Navigation

Press Cmd+L (macOS) or Ctrl+L (Windows/Linux) to open the Navigate dialog and go to a different URL.

Project Structure

File	Description
src/main.ts	Electron main process — window creation, CLI parsing, menu, navigate dialog
src/preload.ts	Minimal preload bridge (electronBridge, currently empty)
run	Bash entry point — CLI parsing, Chrome mode, PM2 start/stop
build/	Compiled TypeScript output

Contributing

npm install                  # Install dependencies
npm run dev                  # Development (watches src/, auto-rebuilds, opens DevTools)
npm start                    # Production-like launch
npm publish --access public  # Publish to npm

Pull requests are welcome! Please describe any behavioral changes and include testing notes.

License

MIT — see LICENSE.