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

```bash 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

```bash 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)

```bash ghost-browser interact click "Sign In" ghost-browser interact type "Email" --type-text "[email protected]" ghost-browser interact type "Password" --type-text "secret123"

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

Step 4: Read page content as markdown

```bash 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

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

Complete Login Example

```bash ghost-browser start ghost-browser navigate https://mysite.com/login ghost-browser wait-ready ghost-browser elements --form-only ghost-browser fill-form '{"email":"[email protected]","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

```bash 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

```bash 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

```bash 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

```bash 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)

```bash ghost-browser interact click "Sign In" # Click by button/link text ghost-browser interact type "Email" --type-text "[email protected]" # Type by label ghost-browser interact click "Products" --index 1 # Click 2nd match if multiple ghost-browser fill-form '{"email":"[email protected]","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.

```bash ghost-browser click "button.submit" # Click by CSS selector ghost-browser type "input#email" "[email protected]" # 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

```bash 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

```bash 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

```bash 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

```bash 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

```bash 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.

```bash 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

```bash 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

```bash 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:

```bash 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 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.