Ghost Browser

Ghost Browser

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 "user@example.com"
ghost-browser interact type "Password" --type-text "secret123"

# Or fill entire forms at once
ghost-browser fill-form '{"email":"user@example.com","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":"me@example.com","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)

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 "user@example.com"  # Type by label
ghost-browser interact click "Products" --index 1  # Click 2nd match if multiple
ghost-browser fill-form '{"email":"a@b.com","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" "a@b.com"   # 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

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:

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.