vibe-browser core
Fast browser automation CLI for AI agents. Chrome/Chromium via CDP, no Playwright or Puppeteer dependency. Supports Chrome, Chromium, Brave, and Edge browsers on macOS, Linux, and Windows.
Installation
npm install -g @startvibecoding/vibe-browser
The core loop
macOS / Linux (bash/zsh)
vibe-browser open <url> # 1. Open a page
vibe-browser snapshot --interactive # 2. See interactive elements
vibe-browser click "button" # 3. Act on elements
vibe-browser snapshot --interactive # 4. Re-snapshot after changes
Windows (PowerShell)
vibe-browser open "<url>" # 1. Open a page
vibe-browser snapshot --interactive # 2. See interactive elements
vibe-browser click "button" # 3. Act on elements
vibe-browser snapshot --interactive # 4. Re-snapshot after changes
Quickstart
macOS / Linux
# Take a screenshot of a page
vibe-browser open https://example.com
vibe-browser screenshot --output home.png
# Search, click a result, and capture it
vibe-browser open https://duckduckgo.com
vibe-browser snapshot --interactive
vibe-browser fill "input[name=q]" "vibe-browser cli"
vibe-browser press Enter
vibe-browser wait text "Results"
vibe-browser snapshot --interactive
vibe-browser click "a.result"
vibe-browser screenshot --output result.png
Windows (PowerShell)
# Take a screenshot of a page
vibe-browser open "https://example.com"
vibe-browser screenshot --output home.png
# Search, click a result, and capture it
vibe-browser open "https://duckduckgo.com"
vibe-browser snapshot --interactive
vibe-browser fill "input[name=q]" "vibe-browser cli"
vibe-browser press Enter
vibe-browser wait text "Results"
vibe-browser snapshot --interactive
vibe-browser click "a.result"
vibe-browser screenshot --output result.png
Browser Discovery
# Auto-detect running browser
vibe-browser discover
# List installed browsers
vibe-browser browsers
# Use specific browser
vibe-browser open --browser brave https://example.com
vibe-browser open --browser edge https://example.com
# Connect to specific CDP endpoint
vibe-browser open --cdp-url ws://127.0.0.1:9222/devtools/browser
Supported Browsers by Platform
| Browser | macOS | Linux | Windows |
|---|---|---|---|
| Chrome | /Applications/Google Chrome.app/Contents/MacOS/Google Chrome |
google-chrome, google-chrome-stable |
%PROGRAMFILES%\Google\Chrome\Application\chrome.exe |
| Chromium | /Applications/Chromium.app/Contents/MacOS/Chromium |
chromium, chromium-browser |
%LOCALAPPDATA%\Chromium\Application\chrome.exe |
| Brave | /Applications/Brave Browser.app/Contents/MacOS/Brave Browser |
brave-browser |
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe |
| Edge | /Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge |
microsoft-edge |
%PROGRAMFILES%\Microsoft\Edge\Application\msedge.exe |
| Chrome Canary | /Applications/Google Chrome Canary.app/... |
— | — |
User Data Directories (for connecting to existing profiles)
| Browser | macOS | Linux | Windows |
|---|---|---|---|
| Chrome | ~/Library/Application Support/Google/Chrome |
~/.config/google-chrome |
%LOCALAPPDATA%\Google\Chrome\User Data |
| Chromium | ~/Library/Application Support/Chromium |
~/.config/chromium |
%LOCALAPPDATA%\Chromium\User Data |
| Brave | ~/Library/Application Support/BraveSoftware/Brave-Browser |
~/.config/BraveSoftware/Brave-Browser |
%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data |
| Edge | ~/Library/Application Support/Microsoft Edge |
~/.config/microsoft-edge |
%LOCALAPPDATA%\Microsoft\Edge\User Data |
Reading a page
vibe-browser snapshot # full tree
vibe-browser snapshot --interactive # interactive elements only (preferred)
vibe-browser snapshot --interactive --compact # compact mode
Snapshot output looks like:
Page: Example - Log in
URL: https://example.com/login
[1] heading "Log in"
[2] form
[3] textbox Email
[4] textbox Password
[5] button "Continue"
[6] link "Forgot password?"
With --interactive, contenteditable rich-text editors (ProseMirror, Quill,
…) are surfaced as editor nodes with an [editable:…] marker. If the page
has no interactive elements, the command prints (no interactive elements
found; page has N top-level nodes, retry without interactive=true) instead of
an empty string — retry without --interactive rather than dumping
get html "body".
For reading content:
vibe-browser get text "h1"
vibe-browser get html "div.content" # capped at 50 KB by default
vibe-browser get html "div.content" --max-bytes 0 # full HTML, no truncation
vibe-browser get html "div.content" --max-bytes 10240 # cap at 10 KB
vibe-browser get attr "a" href
vibe-browser get value "input"
vibe-browser get url
vibe-browser get title
> get html size cap: by default the result is truncated to 50 KB with a
> [truncated: N bytes total, ...] notice to avoid blowing up your context
> window on large SPA pages. Pass --max-bytes 0 for the full document, or
> use get text / a narrower selector when you only need part of the page.
Interacting
vibe-browser click "button"
vibe-browser dblclick "div.item"
vibe-browser hover "a.link"
vibe-browser focus "input"
vibe-browser fill "input" --value "hello"
vibe-browser type "input" " world"
vibe-browser press Enter
vibe-browser check "input[type=checkbox]"
vibe-browser uncheck "input[type=checkbox]"
vibe-browser select "select" --value "option1"
vibe-browser scroll --x 0 --y 500
Waiting
vibe-browser wait selector "div.loaded" # until element appears
vibe-browser wait ms 2000 # dumb wait (last resort)
vibe-browser wait text "Success" # until text appears
vibe-browser wait url "/dashboard" # until URL matches
After any page-changing action, wait for:
- A specific element: wait selector "..."
- URL change: wait url "/new-page"
Common workflows
Log in
vibe-browser open https://app.example.com/login
vibe-browser snapshot --interactive
vibe-browser fill "input[name=email]" "user@example.com"
vibe-browser fill "input[name=password]" "hunter2"
vibe-browser click "button[type=submit]"
vibe-browser wait url "/dashboard"
Extract data
vibe-browser get title
vibe-browser get text "h1"
vibe-browser get text ".price"
vibe-browser get attr "a.main-link" href
vibe-browser eval "document.querySelectorAll('table tr').length"
Screenshot
vibe-browser screenshot --output page.png
vibe-browser screenshot --full-page --output full.png
Flags
--cdp-url string Chrome DevTools Protocol WebSocket URL
--session string Session name (default "default")
--headless Run in headless mode (default true)
--executable-path Path to Chrome executable
--browser string Browser type (chrome, chromium, brave, edge)
Environment Variables
VIBE_BROWSER_CDP_URL Same as --cdp-url
VIBE_BROWSER_SESSION Same as --session
VIBE_BROWSER_BROWSER Same as --browser
VIBE_BROWSER_DEBUG Enable debug logging
VIBE_BROWSER_SOCKET_DIR Override socket directory (see platform-specific defaults below)
CHROME_PATH Path to Chrome executable
Platform-Specific Defaults
| Setting | macOS / Linux | Windows |
|---|---|---|
| Socket directory | ~/.vibe-browser/ or $XDG_RUNTIME_DIR/vibe-browser/ |
%TEMP%\vibe-browser\ |
| Default browser | Auto-detected from PATH | Auto-detected from PATH / Program Files |
> Note: The daemon mode (long-running sessions via Unix socket) is not available on Windows. On Windows, use direct CDP connections (--cdp-url) or launch browser per command.
SDK Usage
import "github.com/startvibecoding/vibe-browser/pkg/client"
c, _ := client.Open(ctx, &client.Options{
CDPURL: "ws://127.0.0.1:9222/devtools/browser",
})
defer c.Close()
c.Navigate(ctx, "https://example.com")
title, _ := c.Title(ctx)
screenshot, _ := c.Screenshot(ctx)
Troubleshooting
Browser not found
# Check installed browsers
vibe-browser browsers
# Or set CHROME_PATH
export CHROME_PATH=/path/to/chrome # macOS/Linux
$env:CHROME_PATH="C:\path\to\chrome.exe" # PowerShell (Windows)
Connection refused
# Discover running browser
vibe-browser discover
# Or let vibe-browser launch Chrome automatically
vibe-browser open https://example.com
Element not found
# Take a fresh snapshot
vibe-browser snapshot --interactive
# Use correct selector
vibe-browser wait selector "button.submit"
vibe-browser click "button.submit"
