cursor-browser-cli

Drive Cursor IDE’s built-in Browser Tab from any CLI agent or shell — Grok Build, Claude Code, Codex, OpenCode, or plain terminal — without leaving Cursor and without spinning up a separate Chrome/Playwright stack.

Stay in a long chat in Cursor’s integrated terminal. Navigate, take accessibility snapshots with refs, click/type/fill by ref, wait for page state, lock the tab, screenshot, and inspect console/network/DOM — all on the same Browser Tab you already see in the IDE.

Grok Build · Claude Code · Codex · OpenCode · shell
              │
              │  CLI  (cursor-browser)
              │  or MCP stdio  (mcp/server.mjs)
              ▼
     localhost HTTP  127.0.0.1:<port>
              │
              ▼
   Cursor extension (workspace host)
              │  cursor.browserView.*
              ▼
     Cursor Browser Tab  (this project window)

Why this exists

The problem

Cursor ships Browser Automation for its own Cursor Agent (chat/composer with built-in browser tools). That is great when you stay inside Cursor Agent.

Many people do not stay there. A common workflow is:

1. Open a project in Cursor

2. Run Grok Build, Claude Code, Codex, or another CLI agent in the integrated terminal

3. Still want to use the in-IDE Browser Tab for UI checks, local apps, auth flows, visual verification, etc.

Those CLI agents cannot call Cursor Agent’s built-in browser tools. Without something else, you end up:

• Opening extra Chrome windows and tabs

• Re-explaining context across tools

• Running a separate Playwright/CDP stack just to “see” the app

• Or bouncing back into Cursor Agent only for browser steps

That breaks the flow: you wanted one IDE window, one Browser Tab, and multiple agents that can share it.

The solution

cursor-browser-cli is a small local stack that lets any agent (or script) control Cursor’s Browser Tab the same way Cursor Agent does — via:

You keep working in the CLI agent. The Browser Tab stays inside Cursor. No second browser product required for day-to-day agent work.

What this is not

This project targets one job: multi-agent access to Cursor’s Browser Tab from CLI/MCP while you work inside Cursor. It is intentionally independent of any external-browser stack so both can coexist without coupling.

Related MCP server: @nimbus21.ai/chrome-devtools-mcp

Bridge recovery (agents / post-reboot)

The CLI talks to a localhost HTTP bridge started by the Cursor extension. The in-IDE Browser Tab can work while that bridge is down.

cursor-browser ensure            # setup + doctor + heal + verify (preferred)
cursor-browser ensure --reload   # after upgrades — multi-window extension code reload
cursor-browser doctor            # ports, extension, version skew, stale state
cursor-browser recover           # self-heal: multi-window restart tokens + wait
cursor-browser recover --reload  # force all windows to reload extension code
cursor-browser windows           # must list live project ports + versions

recover / ensure are safe to run from Grok/Claude/Codex when you see ECONNREFUSED. They self-heal with file triggers only:

1. Prunes dead instances.json / port files

2. Writes ~/.cursor-browser-cli/request-restart (extension watches + polls → restartServer())

3. If still down and Cursor hosts are running: writes request-reload (extension reloads window → re-activate)

4. Waits until a bridge port answers

If the extension is not loaded at all, recover cannot start the server from outside Cursor — run once:

Cmd+Shift+P → Cursor Browser CLI: Restart Server (or Reload Window).

The extension also self-heals on a heartbeat: if activePort is set but TCP is dead, it restarts the HTTP server without any CLI call.

Optional env: CURSOR_BROWSER_NO_AUTO_RECOVER=1 disables auto-recover on connection errors.

Features

Multi-agent by design

• Same Browser Tab for Grok Build, Claude Code, Codex, OpenCode, shell scripts, and humans

• CLI and MCP share the same extension HTTP API

• Workspace routing so multiple Cursor windows do not step on each other

• Optional skill files for Grok / Claude / agents that load SKILL.md

Agent-grade interaction (ref model)

• Accessibility snapshot with refs (e1, e5, …) — YAML-style tree agents can read and act on

• Click / double-click / right-click / type / fill / hover by ref (CSS selector fallback)

• scroll window or element; select-option for <select>

• wait for URL substring, visible text, ref, or CSS selector (reduces agent races)

• --wait-nav after click to wait for URL change; --snap to attach a fresh snapshot after interact

• Lock / unlock the tab during automation so accidental human input does not fight the agent

• Resize viewport

• open / nav print snapshot text by default (use --json for full payload)

Fast, CLI-first

• Single binary-style script on your PATH: cursor-browser

• Low overhead: Node built-ins only, loopback HTTP, no runtime npm deps

• Multi-window: --workspace <folder> or match cwd

• Single-tab policy: reuse one tab; close extras for predictable automation

Under the hood (debug like DevTools)

• Screenshot (PNG path; MCP can return image content when available)

• inspect — meta, counts, headings, links, inputs, body text

• console / network via Cursor getConsoleLogs / getNetworkRequests

• eval — run page JavaScript

Local and contained

• Listens on 127.0.0.1 only

• Per-window port (default base 17373, auto-increments if busy)

• State under ~/.cursor-browser-cli/

• Status bar shows project :port so you know which window is listening

Requirements

• Cursor IDE with Browser Tab / cursor.browserView.* APIs available

• Node.js ≥ 18 (CLI + MCP; no production npm dependencies)

• macOS / Linux / Windows (where Cursor runs)

Install (recommended: npm)

npm install -g cursor-browser-cli

That installs:

If the extension step was skipped (e.g. npm i --ignore-scripts), run:

cursor-browser setup

Then reload each Cursor window you use:

Cmd+Shift+P (or Ctrl+Shift+P) → Developer: Reload Window

Confirm the status bar shows something like your-project :17375, then:

cursor-browser windows
cursor-browser --workspace <project-folder> open https://example.com
cursor-browser --workspace <project-folder> snapshot

Skip automatic setup

CURSOR_BROWSER_SKIP_SETUP=1 npm install -g cursor-browser-cli
cursor-browser setup   # when ready

From source (optional)

git clone https://github.com/bcharleson/cursor-browser-cli.git
cd cursor-browser-cli
npm install          # runs setup
# or: ./scripts/install.sh

Extension commands (inside Cursor)

Settings

Quick start (agent loop)

This is the loop CLI agents should follow:

# 0) Discover this project → bridge port (required with multiple Cursor windows)
cursor-browser windows          # list: project → port
cursor-browser pin              # this cwd's project + port + export lines
eval $(cursor-browser pin --export)
# sets CURSOR_BROWSER_WORKSPACE + CURSOR_BROWSER_CLI_PORT
# prefer workspace name over port (ports can change after recover)

# or pin explicitly:
export WS=my-app   # folder name of the Cursor workspace

# 1) One clean tab + navigate → snapshot with [ref=e…] printed
cursor-browser --workspace $WS close
cursor-browser --workspace $WS open http://localhost:3000

# 2) Interact by ref from the snapshot
cursor-browser --workspace $WS click e5
cursor-browser --workspace $WS fill e3 "hello"
cursor-browser --workspace $WS press Enter

# 3) Wait for navigation / UI (avoid races)
cursor-browser --workspace $WS wait --url /results --timeout 15000
cursor-browser --workspace $WS wait --text "Success"

# 4) Visual / debug
cursor-browser --workspace $WS screenshot /tmp/out.png
cursor-browser --workspace $WS inspect
cursor-browser --workspace $WS console

Rules of thumb

1. Pin first — windows → pin → env or --workspace (never guess with multi-window).

2. Take a fresh snapshot after navigation or large DOM changes before using refs.

3. Prefer ref (e12) over CSS when the snapshot provides one.

4. Prefer open / nav (they return snapshots) over bare navigate without a follow-up snap.

5. Use wait after clicks that change URL or content.

6. Use close if extra tabs pile up; keep one tab for reliability.

7. With multiple Cursor windows, always pass --workspace (or pin via eval $(cursor-browser pin --export)).

CLI reference

cursor-browser [--workspace NAME|PATH] [--port N] <command> [args]

Global flags

Environment variables

Legacy env names from earlier package renames may still be read by clients for compatibility.

Routing commands

Tabs and navigation

Interaction (prefer refs from snapshot)

Wait, viewport, capture, debug

wait flags

Examples:

cursor-browser --workspace my-app wait --url /dashboard --timeout 15000
cursor-browser --workspace my-app wait --text "Welcome"
cursor-browser --workspace my-app wait --ref e12
cursor-browser --workspace my-app wait --selector "button.save"

Multi-window routing order

When you have several Cursor projects open, the CLI picks a target in this order:

1. --port / CURSOR_BROWSER_CLI_PORT

2. --workspace / CURSOR_BROWSER_WORKSPACE / CURSOR_BROWSER_PROJECT

3. Match current cwd to a registered workspace folder (strong match only)

4. Single open instance

5. Fail closed — never silently open another project when multiple bridges are live

Shared ~/.cursor-browser-cli/port is only used when no instances are registered (recovery), not as a multi-window fallback.

cursor-browser windows
cursor-browser pin
eval $(cursor-browser pin --export)
cursor-browser whoami
cursor-browser open http://localhost:3000
# or without env:
cursor-browser --workspace my-app open http://localhost:3000

pin / resolve output (human):

project:  my-app
path:     /Users/you/Developer/my-app
port:     17375
how:      cwd (score 100)
live:     yes

# Pin this project for the rest of the shell/session:
export CURSOR_BROWSER_WORKSPACE='my-app' CURSOR_BROWSER_CLI_PORT=17375

MCP server

Stdio MCP server for agents that prefer tools over shelling out.

After npm install -g cursor-browser-cli, the bin cursor-browser-mcp is on your PATH.

Register

# Grok Build
grok mcp add cursor-browser -- cursor-browser-mcp

# Claude Code
claude mcp add cursor-browser -- cursor-browser-mcp

Any stdio MCP client:

{
  "mcpServers": {
    "cursor-browser": {
      "command": "cursor-browser-mcp"
    }
  }
}

Fallback (from a clone or if the bin is not on PATH):

{
  "mcpServers": {
    "cursor-browser": {
      "command": "node",
      "args": ["/absolute/path/to/cursor-browser-cli/mcp/server.mjs"]
    }
  }
}

Optional env on the server process:

• CURSOR_BROWSER_WORKSPACE

• CURSOR_BROWSER_CLI_PORT

Or pass workspace on each tool call. With multiple Cursor projects open, workspace is required (MCP fails closed instead of opening the wrong project).

Agent pin flow (MCP)

1. browser_windows — list project → port

2. browser_resolve (or browser_pin) — returns workspace, port, and pin instructions

3. Pass that workspace on every subsequent browser_* call

Tools

All tools accept optional workspace (project folder name or path) unless noted. With multiple live bridges, pass it every time.

Screenshot note: When the page returns a data URL, the MCP layer can attach an image content block for vision-capable models, plus a text payload with the saved path.

Skills

npm install -g / cursor-browser setup copies skill/SKILL.md to:

• ~/.grok/skills/cursor-browser/SKILL.md

• ~/.claude/skills/cursor-browser/SKILL.md

• ~/.agents/skills/cursor-browser/SKILL.md

• ~/.cursor/skills/cursor-browser/SKILL.md

• ~/.codex/skills/cursor-browser/SKILL.md

The skill describes only the Cursor Browser Tab. It does not depend on or install any external-browser stack.

The skill teaches agents:

• Always route the correct Cursor window (windows / --workspace)

• Preferred snapshot → ref click/fill → wait loop

• When to screenshot, inspect, console, network

• Failure modes (stale refs, wrong project, connection refused)

Architecture

┌─ Cursor window: your-project ──────────────────────────┐
│  Extension host HTTP  127.0.0.1:1737x                   │
│         │                                              │
│         │  cursor.browserView.*                        │
│         ▼                                              │
│  Browser Tab                                           │
│  · refs via data-cursor-ref after snapshot             │
│  · DOM click/type/fill (not raw CDP Input)             │
└────────────────────────────────────────────────────────┘
                    ▲
                    │  loopback only
     CLI  ·  MCP  ·  scripts
   (Grok / Claude Code / Codex / shell)

On-disk state (~/.cursor-browser-cli/):

Ports start at 17373 and try up to 32 candidates if the preferred port is taken (one port per Cursor window).

How agents should use it

Typical product/UI session

1. browser_windows or cursor-browser windows — list project → port

2. browser_resolve / cursor-browser pin — pin this project (env or workspace arg)

3. open / browser_open on http://localhost:… or staging URL

4. Read refs from the snapshot

5. click / fill / press

6. wait for URL or text

7. New snapshot after major UI change

8. screenshot or inspect when stuck

Multi-project day

Always discover then pin:

cursor-browser windows
cursor-browser pin
eval $(cursor-browser pin --export)

cursor-browser --workspace project-a open http://localhost:3000
cursor-browser --workspace project-b open http://localhost:4000

Or set CURSOR_BROWSER_WORKSPACE in that agent’s shell profile / MCP env.

Switching agents mid-project

The Browser Tab is owned by the Cursor window, not by a single agent process. You can:

1. Use Cursor Agent for some steps (built-in tools)

2. Switch to Claude Code / Grok / Codex in the terminal

3. Continue with cursor-browser or MCP on the same tab

That continuity is the whole point of this tool.

Security

• The HTTP server binds to loopback only (127.0.0.1).

• Anyone who can reach that port on your machine can drive the Browser Tab (navigate, click, run page JS, read console/network).

• Treat it like a local debugger: do not tunnel or expose the port; do not run on untrusted multi-user machines without isolation.

• eval / browser_evaluate execute arbitrary page JavaScript — only run code you trust.

Troubleshooting

Logs: ~/.cursor-browser-cli/bridge.log

Repo layout

cursor-browser-cli/
├── README.md
├── LICENSE                 # MIT
├── package.json            # npm package (bins + postinstall setup)
├── cli/
│   └── cursor-browser      # CLI entry (Node)
├── extension/
│   ├── package.json
│   ├── extension.js        # HTTP API + cursor.browserView.*
│   └── snapshot.js         # Accessibility snapshot + refs
├── mcp/
│   └── server.mjs          # MCP stdio server → bin: cursor-browser-mcp
├── scripts/
│   ├── setup.js            # extension + skills install
│   └── install.sh          # thin wrapper → setup.js
└── skill/
    └── SKILL.md            # Agent skill template

No runtime npm dependencies — Node built-ins only (http, fs, path, os, etc.).

Development notes

• Extension activation: onStartupFinished

• Preferred port configurable via cursorBrowserCli.port

• Clients still understand legacy state dirs / names from earlier renames for smoother upgrades

• After changing extension code: cursor-browser setup (or npm run setup) and Reload Window

• Publish: npm publish (requires npm login)

License

MIT © Brandon Charleson

Contributing / sharing

This repo is intended to be shared as open source so CLI agents in Cursor can share one Browser Tab.

If you publish or fork:

1. Keep the why clear: multi-agent access to Cursor’s Browser Tab

2. Document both CLI and MCP equally

3. Stress workspace routing and the snapshot → ref → wait loop

Issues and PRs that improve multi-window routing, snapshot quality, or agent docs are especially welcome.