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

CODEBLOCK0

INLINECODE3 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

CODEBLOCK1

Output:
CODEBLOCK2

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

CODEBLOCK3

Step 4: Read page content as markdown

CODEBLOCK4

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

Step 5: Wait for dynamic pages

CODEBLOCK5

Complete Login Example

CODEBLOCK6

Restore a Previous Session

CODEBLOCK7

Command Reference

Preferred Commands (use these first)

Command	What it does	Token cost
INLINECODE6	Page overview: title, URL, element counts, flags	~10
INLINECODE7

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

CODEBLOCK8

Navigation & Tabs

CODEBLOCK9

After navigate, all commands automatically target the navigated tab.

Page Understanding

CODEBLOCK10

Text-Based Interaction (preferred)

CODEBLOCK11

CSS Selector Interaction (fallback)

Use these only when text-based interaction fails.

CODEBLOCK12

Cookies & Storage

CODEBLOCK13

Session Management

CODEBLOCK14

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

CODEBLOCK15

Debugging

CODEBLOCK16

Network and console logging run automatically in the background.

Window

CODEBLOCK17

Profile Management

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

CODEBLOCK18

Extension Management

CODEBLOCK19

Challenge Handling

CODEBLOCK20

Challenges are also detected and handled automatically in the background.

Decision Guide

I want to...	Use this
Understand what's on a page	INLINECODE20 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:

CODEBLOCK21

Installation

After installing the skill, run the setup script:

CODEBLOCK22

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	INLINECODE39	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.