dvcrn 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)
| 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 "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
| 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