--- name: browser-pilot description: | Chrome DevTools Protocol (CDP) browser automation, web scraping, crawling. 브라우저 자동화, 웹 스크래핑, 크롤링. Features\/기능: screenshot with region control 영역지정스크린샷, viewport control 뷰포트제어, PDF generation PDF생성, web scraping 웹스크래핑, data extraction 데이터추출, form filling 폼작성, login automation 로그인자동화, click\/input 클릭\/입력, element finder 요소찾기, tab management 탭관리, cookie control 쿠키제어, JavaScript execution JS실행, page navigation 페이지이동, wait for element 요소대기, scroll 스크롤, accessibility tree 접근성트리, console messages 콘솔메시지, network idle 네트워크대기, back\/forward 뒤로\/앞으로, reload 새로고침, file upload 파일업로드, React compatibility React호환성, Smart Mode with Interaction Map 스마트모드. Selectors 셀렉터: CSS selectors (ID, class, attribute), XPath selectors with wildcard * (text-based, structural), XPath indexing (select N-th element with same text). Smart Mode: text-based element search with automatic selector generation. Bot detection bypass 봇감지우회 (navigator.webdriver=false). Auto Chrome connection 자동크롬연결. Headless\/headed mode. Daemon-based architecture 데몬기반. Interaction Map System 인터랙션맵. React\/framework compatibility React\/프레임워크호환성. --- # browser-pilot ## Purpose Automate Chrome browser using Chrome DevTools Protocol (CDP) with a daemon-based architecture. Maintains persistent browser connection for instant command execution. Features Smart Mode with Interaction Map for reliable element targeting using text-based search instead of brittle selectors. **Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window. ## When to Use Use browser-pilot when tasks involve: - Browser automation, web scraping, data extraction - Screenshot capture, PDF generation - Form filling, login automation, element interaction - Tab management, cookie control, JavaScript execution - Tasks requiring text-based element selection ("click the 3rd Delete button") - Bot detection bypass requirements (navigator.webdriver = false) ## ⚠️ Important Guidelines **When to Ask User:** Use AskUserQuestion tool if: - Task requirements unclear or ambiguous - Multiple implementation approaches possible - Element selectors not working despite troubleshooting - User intent uncertain (e.g., "automate this" without specifics) **DO NOT** guess or assume user requirements. Always clarify first. ## Prerequisites Chrome must be installed. Local scripts initialize automatically on session start (no manual setup required). ## Getting Help All commands support `--help` for detailed options: ```bash # See all available commands node .browser-pilot\/bp --help # Get help for specific command node .browser-pilot\/bp --help ``` ## Architecture **Daemon-based design:** - Background daemon maintains persistent CDP connection - CLI commands communicate via IPC - Auto-starts on first command, stops at session end - 30-minute inactivity timeout **Interaction Map System:** - Auto-generates JSON map of interactive elements on page load - Enables text-based search with automatic selector generation - Handles duplicates with indexing - 10-minute cache with auto-regeneration ## Core Workflow ### 1. Extract Required Information From user's request, identify: - Target URL(s) to visit - Actions to perform (screenshot, click, fill, etc.) - Element identifiers (text content, CSS selectors, or XPath) - Output file names (for screenshots\/PDFs) - Data to extract or forms to fill When information is missing or ambiguous, use AskUserQuestion tool. ### 2. Execute Commands All commands use `.browser-pilot\/bp` wrapper script. Replace placeholders with actual values. **Navigation:** ```bash node .browser-pilot\/bp navigate -u node .browser-pilot\/bp back node .browser-pilot\/bp forward node .browser-pilot\/bp reload ``` **Interaction (Smart Mode - Recommended):** ```bash # Text-based element search (map auto-generated) # No quotes for single words node .browser-pilot\/bp click --text Login --type button node .browser-pilot\/bp fill --text Email -v # Use quotes when text contains spaces node .browser-pilot\/bp click --text "Sign In" --type button node .browser-pilot\/bp fill --text "Email Address" -v # Handle duplicates with indexing node .browser-pilot\/bp click --text Delete --index 2 # Filter visible elements only node .browser-pilot\/bp click --text Submit --viewport-only # Type aliases (auto-expanded) node .browser-pilot\/bp click --text Search --type input # Matches: input, input-text, input-search, etc. # Tag-based filtering (HTML tag) node .browser-pilot\/bp click --text Submit --tag button # Matches all