cursor-browser

cursor-browser-cli

Control Cursor’s Browser Tab in the matching project window.

This skill is only for the in-IDE Browser Tab. It does not drive an external desktop browser product. Other browser tools (if installed on the machine) are separate and independent — use those when you need a full browser profile, existing cookie sessions, or non-Cursor windows. Prefer this tool for day-to-day app UI work inside Cursor (local servers, fast ref loops, same tab as the IDE).

Install via npm install -g cursor-browser-cli, or clone this repo and run npm install.

Always pin the project first (required multi-window)

Each Cursor project has its own bridge on its own port. Never open a tab until you know which project/port you are targeting.

# 1) What bridges are live? (project → port)
cursor-browser windows

# 2) What project is THIS cwd / workspace?
cursor-browser pin
# or:
cursor-browser --workspace <project-folder> pin

# 3) Pin for the rest of the shell session
eval $(cursor-browser pin --export)
# sets CURSOR_BROWSER_WORKSPACE + CURSOR_BROWSER_CLI_PORT

Or pass every time:

cursor-browser --workspace <project-folder> whoami
cursor-browser --workspace <project-folder> open http://localhost:3000

Prefer --workspace <name> over raw port. Ports can change after recover / Restart Server; the project name stays stable.

Multi-project days: always pass --workspace (or pin via eval $(… pin --export)).

Agent loop (preferred)

# 0) Discover + pin (once per session / project)
cursor-browser windows
cursor-browser pin
eval $(cursor-browser pin --export)
# confirm:
cursor-browser whoami

# 1) Single tab + navigate → ref snapshot printed as text
cursor-browser open http://localhost:3000
# or
cursor-browser nav http://localhost:3000

# 2) Read refs from snapshot output (e1, e5, …)

# 3) Interact by ref
cursor-browser click e5
cursor-browser fill e3 "value"
cursor-browser type e3 "more"
cursor-browser hover e2
cursor-browser press Enter
cursor-browser scroll --y 600
cursor-browser select-option e7 "option-value"

# Optional: fresh refs after same-page interact
cursor-browser fill e3 "x" --snap
# After a navigation click, prefer wait + snapshot (most reliable)
cursor-browser click e5 --wait-nav --timeout 15000
cursor-browser snapshot
# --snap on a nav click also works (CLI falls back if needed) but is slower

# 4) Wait for state (avoid races)
cursor-browser wait --url /dashboard --timeout 15000
cursor-browser wait --text "Welcome"
cursor-browser wait --ref e12

# 5) Lock while automating (optional)
cursor-browser lock
# ... actions ...
cursor-browser unlock