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 appears internally consistent with its stated purpose (an automated Chrome controller using nodriver); the requested binaries, included files, and runtime instructions match a browser automation tool.

Purpose & Capability

Name/description, required binaries (python3 + Chrome/Chromium), the nodriver requirement in requirements.txt, the CLI wrapper, Python daemon, and a small extension to patch pointer events all align with an automated Chrome/browser-control skill.

Instruction Scope

Runtime instructions direct the agent to run the ghost-browser CLI for navigation, element inspection, form fill, session save/load, page reading, screenshots, file download/upload, and JS eval. Those actions are expected for browser automation, but the skill will read and write persistent state (profiles, sessions, cookies) under the user's home directory (~/.openclaw/.../ghost-browser/state) and exposes an eval command (arbitrary JS execution) and download/upload functionality — capabilities that are powerful and should be used only for trusted pages/tasks.

Install Mechanism

No centralized install spec, but setup.sh creates a local Python venv under the skill directory and installs nodriver from PyPI (requirements.txt). This is a normal install method for Python tools but does pull code from the public package index (pip). There are no suspicious remote downloads or URL shorteners in the provided files.

Credentials

The skill does not request external environment variables or unrelated credentials. It stores profiles, session files, and logs under a workspace directory in the user's home — expected for a browser that saves cookies and localStorage, but those stored session artifacts can contain sensitive authentication tokens.

Persistence & Privilege

The skill creates a local virtual environment, an executable CLI wrapper, and persistent state files under the user's home directory. It is not marked always:true and does not modify other skills; persistent state and executable creation are expected for this kind of tool but represent lasting changes on the host.

Assessment

This skill is coherent for browser automation, but review and accept these trade-offs before installing: it will create a .venv and write state, profiles, sessions, cookies, and logs under ~/.openclaw/.../ghost-browser/state — session files may contain sensitive auth tokens, so avoid saving secrets there. The setup script installs nodriver from PyPI (ensure you trust that package/version). The daemon exposes commands for arbitrary JS eval, download/upload, and network logging; only navigate it to trusted pages and consider running the skill in an isolated environment (container or VM) if you have sensitive data on the host. If you want extra assurance, inspect scripts/ghost_browser.py and extensions content, and run setup.sh manually to review pip install output before use.

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

Capability Disclosure

This skill is a full browser automation tool. By design, it includes capabilities that security scanners may flag:

• eval — Executes arbitrary JavaScript in the browser context. This is standard for any browser automation tool (equivalent to Playwright's page.evaluate() or Puppeteer's page.evaluate()).
• upload / download — Reads local files for upload and saves downloaded files to disk. Required for any browser that handles file inputs or downloads.
• session save/load — Persists cookies, localStorage, and sessionStorage to JSON files under state/sessions/. These files may contain authentication tokens. Delete sessions you no longer need.
• install-extension / load-extension — Loads Chrome extensions programmatically. On macOS, extension installation from .crx files may use osascript for Chrome Web Store installs.
• Anti-detection — Uses nodriver (instead of Playwright/Puppeteer) to avoid setting navigator.webdriver=true. Blocks detectable CDP domains (Runtime.enable, Console.enable). Patches mouse event coordinates to avoid synthetic click detection. These are stealth features for bypassing bot detection on websites — not evasion of security tools on your machine.

None of these capabilities access data outside the browser or the skill's own state/ directory. The skill does not phone home, collect telemetry, or transmit data to any third party.