realbrowser

Realbrowser is an agent skill and small local CLI for fast target-first browser automation against Chrome/Chromium. It is built for the cases where the useful state is in the browser the developer is already using: signed-in profiles, cookies, local storage, active tabs, console logs, network traffic, downloads, and local app state.

The current CLI is grouped and target-first:

realbrowser [global flags] <group> <command> [args] [flags]

Acquire or create one tab target first, then pass -t <label> or --handle to reads, actions, screenshots, console, network, state, dialogs, performance, downloads, and exports.

What It Provides

An agent skill named realbrowser (works with Claude Code, Codex, and other

agent platforms).

A zero-dependency Node CLI at skills/realbrowser/scripts/realbrowser.mjs.
Portable wrappers:
skills/realbrowser/scripts/realbrowser for macOS/Linux shells.
skills/realbrowser/scripts/realbrowser.ps1 for PowerShell.
skills/realbrowser/scripts/realbrowser.cmd for Windows cmd.exe.
Signed-in profile attach through Chrome/Chromium DevTools endpoints.
Anonymous managed sessions for clean browser state.
Stable labeled tab targets, scoped per owner/session.
Target leases for mutating commands so parallel sessions do not

accidentally navigate, close, or click each other's tabs.

Compact page reads, structured item extraction, screenshots, console logs,

network request/response capture, uploads, guarded submits, downloads, and PDF export.

Requirements

Node.js 22 or newer.
Chrome or a Chromium-family browser.
A local machine where Chrome DevTools access is acceptable for the requested

profile/session.

Installation

Claude Code

Add the marketplace, then install the plugin:

/plugin marketplace add darkamenosa/realbrowser
/plugin install realbrowser@realbrowser

To update later:

/plugin marketplace update realbrowser
/plugin update realbrowser@realbrowser

Local development install:

/plugin marketplace add /path/to/realbrowser
/plugin install realbrowser@realbrowser

The skill auto-activates when tasks involve browser interaction, screenshots, console logs, network debugging, or form automation.

Codex

Place the repo under $HOME/.codex/skills/realbrowser and use the

agents/openai.yaml configuration.

Standalone CLI

node skills/realbrowser/scripts/realbrowser.mjs help

Run the built-in checks:

skills/realbrowser/scripts/realbrowser self-test

Common Flows

Parallel sessions:

export REALBROWSER_OWNER=my-project
realbrowser session use profile:chrome:Default
realbrowser tab ensure http://localhost:3000 --profile chrome:Default --label app --background
realbrowser read observe -t app

REALBROWSER_OWNER or --owner <id> scopes labels and default context. Without an explicit owner, Realbrowser uses the current agent/terminal session when one is available, falling back to the project path. Mutating commands claim a target lease; if another owner already owns that tab, rerun with --take-lease only when you intentionally want to take it over. tab ensure creates a fresh tab instead of reusing another owner's URL match.

Anonymous page:

realbrowser tab ensure https://example.com --anonymous --session check --label page --background
realbrowser read observe -t page --anonymous --session check

Visible Chrome Incognito window:

realbrowser tab ensure https://example.com --anonymous --session private --label page --front --incognito
realbrowser read observe -t page --anonymous --session private

Signed-in profile:

realbrowser profile list --active
realbrowser tab list "localhost" --profile chrome:Default
realbrowser tab ensure http://localhost:3000 --profile chrome:Default --label app --background
realbrowser read observe -t app --profile chrome:Default

Console and network evidence:

realbrowser console list -t app --errors --limit 50
realbrowser console capture -t app --reload --duration 3000 --out tmp/console.json
realbrowser network capture -t app --reload --duration 5000 --out tmp/network.json
realbrowser network body -t app req_12 --response --out tmp/req_12-response.json --full

Actions and uploads:

realbrowser action state -t app --root active --compact --screenshot --annotate-refs
realbrowser action fill -t app e1 "caption text"
realbrowser action upload -t app --root active --input-ref e2 ~/Downloads/media.png
realbrowser action submit -t app --root active --text "Submit"

Screenshots and exports:

realbrowser screenshot capture -t app tmp/app.png
realbrowser screenshot full -t app tmp/app-full.png
realbrowser screenshot device -t page --anonymous --session responsive --devices desktop:1440x900,tablet:768x1024,mobile:390x844 tmp/page
realbrowser export pdf -t app tmp/page.pdf --print-background

Operating Model

Use the smallest command that answers the question:

profile list --active to discover usable signed-in profile endpoints.
tab list, tab select, tab ensure, and tab new to acquire a target.
read observe, read size, read query, read items, read item, and

read snapshot for compact page state and structured content.

action state before mutating the page, then act on current refs.
console and network for debugging evidence.
screenshot and export pdf for visual artifacts.

Do not start from broad HTML or whole-page dumps. Use --out for large reads, network bodies, HAR files, screenshots, and traces so they can be inspected with local tools instead of sent through model context.

Profile Safety

With --profile, existing browser tabs may be diagnostic only when CDP is browser-scoped and the tab was not created by Realbrowser through that profile. If a named-profile open needs a proven target, create a new tab through the profile with tab ensure <url> --profile <profile> --label <label>.

--anonymous creates isolated temporary browser state. It is not network anonymity and is not the same as Chrome's visible Incognito UI. Add

--incognito or --private only when a visible private window is explicitly needed.

Realbrowser should keep signed-in profile work in the background when possible. Use --front only for explicit visual handoff. tab ensure --background performs verified browserContextId discovery when possible.

--best-effort-background is only for stopped-profile launch risk and must not OS-launch an already-running browser-scoped profile.

Chrome approval prompts are controlled by Chrome, not the skill. Realbrowser reduces repeated prompts by reusing the same direct DevToolsActivePort WebSocket and daemon per browser endpoint. After a browser/computer restart, a signed-in real Chrome profile can still require Chrome's approval once; managed anonymous sessions avoid signed-in-profile approval but do not contain the user's logged-in state.

Plugin Structure

realbrowser/
├── .claude-plugin/
│   └── plugin.json              # Claude Code plugin manifest
├── skills/
│   └── realbrowser/
│       ├── SKILL.md             # Skill instructions
│       ├── scripts/             # CLI and wrappers
│       │   ├── realbrowser      # macOS/Linux shell wrapper
│       │   ├── realbrowser.cmd  # Windows cmd wrapper
│       │   ├── realbrowser.ps1  # PowerShell wrapper
│       │   └── realbrowser.mjs  # Node CLI implementation
│       └── references/          # Detailed documentation
│           ├── commands.md
│           ├── workflows.md
│           └── design-notes.md
├── agents/
│   └── openai.yaml              # Codex agent configuration
├── README.md
├── CHANGELOG.md
└── LICENSE

Development Notes

Realbrowser is intentionally thin and portable:

Keep workflow guidance in skills/realbrowser/SKILL.md.
Keep command details in skills/realbrowser/references/commands.md and

skills/realbrowser/references/workflows.md.

Keep the implementation in skills/realbrowser/scripts/realbrowser.mjs unless

a boundary becomes stable enough to justify another file.

Add or update self-test coverage for parser, help, state, and CLI behavior

regressions.

Useful checks:

skills/realbrowser/scripts/realbrowser --version
skills/realbrowser/scripts/realbrowser help
skills/realbrowser/scripts/realbrowser self-test