Ghost Browser

Automated Chrome browser using nodriver for AI agent web tasks. Full CLI control with LLM-optimized commands — text-based interaction, markdown output, sessi...

Security Scan

The skill's stated purpose (automated Chrome control via nodriver) is plausible and most required pieces are present, but packaging and install inconsistencies and local persistence behavior are concerning and warrant caution before installing.

Purpose & Capability

The name/description align with what the files implement: a Python-based Chrome automation daemon using nodriver. Required binaries (python3, Chrome/Chromium) and a pip dependency on nodriver are appropriate. However the package shows signs of sloppy packaging: _meta.json version differs from registry metadata, and the repo/source/homepage are unknown — reducing traceability.

Instruction Scope

SKILL.md instructs the agent to use the local ghost-browser CLI for navigation, element interaction, and session save/load. The runtime instructions stay within the stated purpose (browser automation). They do direct the agent to persist and restore sessions (cookies/localStorage), which will store authentication state locally — expected for this functionality but sensitive.

Install Mechanism

The registry declares no install spec, but repository includes setup.sh and requirements.txt that create a venv and pip-install nodriver. That mismatch is an inconsistency. The setup.sh also tries to chmod +x a script path (scripts/ghost-browser) that does not appear in the file manifest (the provided script is scripts/stealth_browser.py), which likely means the packaged setup is broken or mismatched. Because the skill executes local Python and installs packages, you should not run setup scripts without review.

Credentials

No environment variables or external credentials are requested. The code writes state, profiles, logs, cookies and session files into ~/.openclaw/... which is proportional to a browser automation tool but means the skill will store potentially sensitive cookies/auth tokens on disk under the user's account.

Persistence & Privilege

The skill does persist state (profiles, sessions, cookies) to the user's home directory. It is not force-included (always:false) and does not request elevated system privileges, but persistence of session cookies/localStorage increases the sensitivity of what is stored locally and the blast radius if the skill were compromised.

What to consider before installing

This skill mostly does what it says (Chrome automation using nodriver), but there are packaging and install inconsistencies and it will store session cookies and profiles locally. Before installing: 1) Review the full Python script (scripts/stealth_browser.py) for any network endpoints or unexpected behavior you don't trust. 2) Do not run setup.sh blindly — it installs packages and attempts to make a CLI executable but references a non-existent path (scripts/ghost-browser), indicating a broken package. 3) Consider running the skill in an isolated environment (VM/container) or test account to avoid exposing real credentials. 4) If you plan to persist sessions, be aware cookies/localStorage are stored under ~/.openclaw/... and can contain sensitive tokens. 5) Prefer skills with an identifiable source/homepage or official releases; if you need this capability, request a corrected package (matching filenames and a clear install spec) or a signed release from the author.

Automated Chrome browser for AI agent web tasks. Powered by nodriver for reliable browser control. Every command is designed to minimize token usage and maximize accuracy.

Use for: web automation, screenshots, page reading, form filling, scraping, cookie/session management, and persistent browser profiles.

How to Browse — Follow This Workflow

ALWAYS use this workflow. Never use raw content (HTML) or CSS-selector click/type as your first choice.

Step 1: Navigate and understand the page

ghost-browser navigate https://example.com
ghost-browser wait-ready
ghost-browser page-summary

page-summary returns: page title, URL, element counts (links/buttons/inputs/forms), whether there's a login form, and a short text preview. Costs ~10 tokens.

Step 2: See what you can interact with

ghost-browser elements              # Numbered list of ALL interactive elements
ghost-browser elements --form-only  # Just form inputs (for login/signup/search)

Output:

[0] link "Home" → /
[1] link "Products" → /products
[2] button "Sign In"
[3] input[email] "Email address"
[4] input[password] "Password"
[5] submit "Log In"

Step 3: Interact by visible text (NOT CSS selectors)

ghost-browser interact click "Sign In"
ghost-browser interact type "Email" --type-text "[e-mail]"
ghost-browser interact type "Password" --type-text "secret123"

# Or fill entire forms at once
ghost-browser fill-form '{"email":"[e-mail]","password":"secret123"}' --submit

Step 4: Read page content as markdown

ghost-browser readable                    # Full page as clean markdown
ghost-browser readable --max-length 5000  # Limit length to save tokens

Never use content — it returns raw HTML which wastes thousands of tokens. Use readable instead.

Step 5: Wait for dynamic pages

ghost-browser wait-ready             # Wait for network idle + DOM stable
ghost-browser wait-ready --timeout 10

Complete Login Example

ghost-browser start
ghost-browser navigate https://mysite.com/login
ghost-browser wait-ready
ghost-browser elements --form-only
ghost-browser fill-form '{"email":"[e-mail]","password":"mypass"}' --submit
ghost-browser wait-ready
ghost-browser page-summary           # Verify login succeeded
ghost-browser session save mysite    # Save auth state for later

Restore a Previous Session

ghost-browser start --profile mysite
ghost-browser session load mysite
ghost-browser navigate https://mysite.com/dashboard
ghost-browser page-summary

Command Reference

Preferred Commands (use these first)

Command	What it does	Token cost
page-summary	Page overview: title, URL, element counts, flags	~10
elements	Numbered list of buttons, links, inputs	~50-200
elements --form-only	Just form inputs	~10-50
readable	Full page as clean markdown	~500-10000
readable --max-length N	Page markdown capped at N chars	controlled
interact click "text"	Click by visible text	action
interact type "label" --type-text "value"	Type by label/placeholder text	action
fill-form '{"field":"value"}' --submit	Fill and submit a form	action
hover "text" --by-text	Hover by visible text	action
wait-ready	Wait for page to finish loading	~5
session save <name>	Save cookies + localStorage + sessionStorage	~10
session load <name>	Restore full auth state	~10

Lifecycle

ghost-browser start                          # Start browser daemon
ghost-browser start --headless               # Run without visible window
ghost-browser start --profile work           # Use named profile (persistent data)
ghost-browser start --extension /path/ext    # Load unpacked Chrome extension
ghost-browser start --proxy socks5://host:port  # Use proxy
ghost-browser stop                           # Graceful shutdown
ghost-browser status                         # Check if running
ghost-browser status --json                  # Machine-readable status
ghost-browser health                         # Quick health check

Navigation & Tabs

ghost-browser navigate <url>                 # Navigate current tab (or reuse matching tab)
ghost-browser navigate <url> --force-new     # Always open new tab
ghost-browser tabs                           # List open tabs with IDs
ghost-browser tabs --json                    # Machine-readable tab list
ghost-browser activate-tab <ID>              # Switch to a tab by ID
ghost-browser close-tab <ID>                 # Close a tab by ID
ghost-browser wait-ready                     # Wait for page to fully load
ghost-browser wait-ready --timeout 10        # Custom timeout in seconds

After navigate, all commands automatically target the navigated tab.

Page Understanding

ghost-browser page-summary                   # Quick overview (~10 tokens)
ghost-browser elements                       # All interactive elements (numbered)
ghost-browser elements --form-only           # Form inputs only
ghost-browser elements --limit 50            # Cap at 50 elements
ghost-browser readable                       # Full page as markdown
ghost-browser readable --max-length 5000     # Limit output length
ghost-browser content                        # Raw HTML (avoid — use readable instead)

Text-Based Interaction (preferred)

ghost-browser interact click "Sign In"       # Click by button/link text
ghost-browser interact type "Email" --type-text "[e-mail]"  # Type by label
ghost-browser interact click "Products" --index 1  # Click 2nd match if multiple
ghost-browser fill-form '{"email":"[e-mail]","password":"x"}' --submit
ghost-browser hover "Menu" --by-text         # Hover by visible text

CSS Selector Interaction (fallback)

Use these only when text-based interaction fails.

ghost-browser click "button.submit"          # Click by CSS selector
ghost-browser type "input#email" "[e-mail]"   # Type by CSS selector
ghost-browser find "h1"                      # Find elements by selector
ghost-browser hover ".dropdown"              # Hover by CSS selector
ghost-browser wait ".loaded" --timeout 10    # Wait for element to appear
ghost-browser scroll --down                  # Scroll down
ghost-browser scroll --up                    # Scroll up
ghost-browser scroll --to 500               # Scroll to Y position
ghost-browser eval "document.title"          # Execute arbitrary JavaScript

Cookies & Storage

ghost-browser cookies                        # List all cookies
ghost-browser cookies --domain example.com   # Filter by domain
ghost-browser set-cookie name value          # Set a cookie
ghost-browser set-cookie name value --domain .example.com  # Set with domain
ghost-browser clear-cookies                  # Clear all cookies
ghost-browser clear-cookies --domain example.com  # Clear for domain
ghost-browser save-cookies --file cookies.json  # Export cookies to JSON
ghost-browser load-cookies cookies.json      # Import cookies from JSON
ghost-browser storage list                   # List localStorage entries
ghost-browser storage list --session         # List sessionStorage entries
ghost-browser storage get <key>              # Get a value
ghost-browser storage set <key> <value>      # Set a value
ghost-browser storage delete <key>           # Delete a key
ghost-browser storage clear                  # Clear all localStorage

Session Management

ghost-browser session save <name>            # Save cookies + localStorage + sessionStorage
ghost-browser session load <name>            # Restore full auth state

Sessions are saved locally under state/sessions/<name>.json. They contain cookies and storage data needed to restore an authenticated state. Delete session files when no longer needed.

Files & Media

ghost-browser screenshot                         # Screenshot to auto-named file
ghost-browser screenshot --output ./page.png     # Screenshot to specific file
ghost-browser pdf --output page.pdf              # Save page as PDF
ghost-browser pdf --output page.pdf --landscape  # Landscape PDF
ghost-browser upload photo.jpg                   # Upload file (auto-detect file input)
ghost-browser upload doc.pdf --selector "#file"  # Upload to specific file input
ghost-browser download <url> --output file.pdf   # Download a file

Debugging

ghost-browser network-log                    # View recent network requests
ghost-browser network-log --limit 20         # Limit entries
ghost-browser network-log --filter api       # Filter by URL substring
ghost-browser network-log --clear            # Clear the log
ghost-browser console-log                    # View JS console output
ghost-browser console-log --level error      # Show only errors
ghost-browser console-log --clear            # Clear the log
ghost-browser eval "document.title"          # Execute JavaScript and return result

Network and console logging run automatically in the background.

Window

ghost-browser window --size 1920x1080        # Resize window
ghost-browser window --position 0x0          # Reposition window

Profile Management

Profiles persist browser data (history, cookies, extensions) across sessions.

ghost-browser profile list                   # List profiles with sizes
ghost-browser profile create <name>          # Create new profile
ghost-browser profile delete <name>          # Delete a profile and its data
ghost-browser profile default                # Show default profile
ghost-browser profile default <name>         # Set default profile
ghost-browser profile clone <src> <dst>      # Clone a profile

Extension Management

ghost-browser install-extension <source>     # Install from Web Store URL/ID or .crx file
ghost-browser install-extension <source> --name custom-name  # Install with custom folder name
ghost-browser list-extensions                # List all installed extensions
ghost-browser remove-extension <name>        # Remove an installed extension
ghost-browser load-extension <name>          # Load extension into running browser
ghost-browser load-extension                 # Load all extensions
ghost-browser unload-extension <name>        # Unload extension from running browser

Challenge Handling

ghost-browser cf-solve                       # Handle Cloudflare challenges (all tabs)
ghost-browser cf-solve --tab <ID>            # Handle on specific tab

Challenges are also detected and handled automatically in the background.

Decision Guide

I want to...	Use this
Understand what's on a page	page-summary then elements if needed
Read page text content	readable (NOT content)
Click a button	interact click "Button Text"
Fill a login form	fill-form '{"email":"...","password":"..."}' --submit
Type into a specific field	interact type "Field Label" --type-text "value"
Wait for page to load	wait-ready
See what I can click/type	elements or elements --form-only
Save login for later	session save sitename
Restore a saved login	session load sitename
Debug a failing request	network-log --filter domain.com
Check for JS errors	console-log --level error
Take a screenshot	screenshot --output ./page.png
Run custom JavaScript	eval "your code here"

JSON Output

All commands support --json for machine-readable output:

ghost-browser page-summary --json
ghost-browser elements --json
ghost-browser readable --json
ghost-browser status --json

Installation

After installing the skill, run the setup script:

bash setup.sh

This creates a Python virtual environment and installs dependencies automatically.

Requirements

• Python 3.8+
• Google Chrome installed on the system
• nodriver (installed automatically by setup.sh)

Data & Privacy

This skill stores the following data locally under its state/ directory:

Data	Location	Contains
Browser state	state/browser.json	Port numbers, process ID
Logs	state/browser.log	Daemon debug logs
Profiles	state/profiles/	Chrome user data (history, cookies)
Sessions	state/sessions/	Saved auth state (cookies, localStorage)

To clean up: delete the state/ directory to remove all persistent data. Use ghost-browser profile delete <name> to remove individual profiles.

Session and cookie files may contain authentication tokens. Handle them carefully and delete when no longer needed.

Security

• Browser control server binds to 127.0.0.1 only (localhost, not network-accessible)
• The skill does not modify any files outside its own directory
• No environment variables or external credentials are required
• All persistent data is stored under the skill's state/ directory