Launch a new browser session via Botasaurus with anti-detection enabled.

The browser stays alive across all subsequent tool calls until close_session is called. Optionally navigate to an initial URL.

Args: url: Initial URL to navigate to after launch. If omitted, opens a blank page. headless: Run browser in headless mode. Default: false (headed, for observation). profile: Optional Chrome profile for session persistence. A bare name (e.g., 'work-portal') creates a Scout-managed profile at /.scout/profiles// that persists cookies, localStorage, and all browser state across sessions. An absolute path (e.g., 'C:\Users...\User Data') uses an existing Chrome profile directory directly. If omitted, a temporary profile is used and deleted on close. proxy: Optional proxy URL (e.g., 'http://user:pass@host:port'). WARNING: Using a proxy triggers botasaurus-driver's proxy authentication subsystem, which imports javascript-fixes — a package that runs 'npm install' at import time without a lockfile. Only use proxy in trusted environments where Node.js is installed. download_dir: Directory for downloaded files. Default: '/.scout/downloads'. Relative paths are resolved from the server's working directory. connection_mode: How to connect to Chrome. 'launch' (default) starts a new browser instance. 'extension' connects to your existing Chrome via the Scout extension, preserving logged-in sessions. allowed_domains: Optional list of domains allowed for fill_secret credential typing and cross-origin navigation (extension mode). Example: ['example.com', 'login.example.com']. If omitted, fill_secret works on any domain (with a warning). allow_localhost_port: Optional port number (1-65535) to allow localhost/loopback navigation on. Example: 3000 permits http://localhost:3000 only. If omitted, localhost is blocked. The SCOUT_ALLOW_LOCALHOST env var overrides this to allow all ports.

Check the status of the Scout Chrome extension connection.

Returns the extension connection status: whether the relay server is running, whether the extension is connected, and installation instructions if needed.

Perform deep reconnaissance on the current page state.

Returns a structural overview of the page: metadata, iframe hierarchy, shadow DOM boundaries, and element counts. Use find_elements to search for specific interactive elements by text, type, or selector.

Args: session_id: Active session ID from launch_session. focus_frame: Optional iframe CSS selector to scout instead of the full page. detail_level: 'summary' (default) returns compact overview with element counts. 'full' returns all interactive elements (large response).

Search for specific interactive elements on the current page.

Returns matching elements with selectors, text, and attributes. Call scout_page_tool first to cache the page structure, then use this tool to find specific elements by text, type, or CSS selector.

Args: session_id: Active session ID. query: Text or selector to search for (case-insensitive substring match). Matches against element text, selector, id, name, aria-label, placeholder, href. element_types: Filter by tag name, e.g. ['button', 'input', 'a']. visible_only: Only return visible elements. Default: true. frame_context: Limit search to a specific iframe (use selector from scout report). max_results: Maximum elements to return. Default: 25.

Perform a single interaction in the live browser session.

Supports clicking, typing, selecting, navigating, scrolling, and waiting. Always scout after executing an action to observe the result.

Args: session_id: Active session ID. action: The action to perform. selector: CSS selector of the target element. Required for click, type, select, hover, clear, upload_file. value: Text to type, option to select, URL to navigate to, key to press, wait duration, or file path to upload. frame_context: Iframe selector path for the target element. Use 'main' or omit for top-level. wait_after: Milliseconds to wait after action completes. Default: 500.

Type a secret value from .env into a form field without exposing it in the conversation.

The server reads the value from the .env file and types it directly into the target element. The actual value never appears in tool parameters or responses.

Args: session_id: Active session ID. env_var: Name of the environment variable in .env (e.g., 'APP_PASSWORD'). selector: CSS selector of the target input field. frame_context: Iframe selector path for the target element. Use 'main' or omit for top-level. clear_first: Clear the field before typing. Default: true. wait_after: Milliseconds to wait after typing. Default: 500.

Execute arbitrary JavaScript in the page context and return the result.

Use this to debug click failures, read shadow DOM content, dispatch custom events, extract data, or perform any DOM operation not covered by other tools.

Args: session_id: Active session ID. script: JavaScript code to execute. The last expression is returned as the result. Scripts with explicit 'return' statements also work for backward compatibility. frame_context: Iframe selector path for execution context. Use 'main' or omit for top-level.

Capture a screenshot of the current page. The screenshot is always saved to disk.

By default, also returns the image inline so Claude can see it (~1,600 tokens at typical browser resolution). Set return_image=false when capturing screenshots as file artifacts that don't need visual analysis — the file_path in the JSON response is sufficient to reference or copy the file.

Args: session_id: Active session ID. format: Image format: 'png' or 'jpeg'. Default: 'png'. quality: JPEG quality (1-100). Only used when format='jpeg'. clip_x: Left coordinate of clip region (viewport pixels). clip_y: Top coordinate of clip region (viewport pixels). clip_width: Width of clip region. clip_height: Height of clip region. full_page: Capture the full scrollable page, not just viewport. Default: false. Note: pages with lazy-loaded content may still show incomplete results. return_image: Return image inline for visual inspection. Default: true. Set to false when collecting screenshots as file artifacts to save ~1,600 tokens per screenshot.

Inspect a single DOM element in detail — visibility, position, shadow DOM, overlays, and more.

Use this to diagnose why a click didn't work, check if an element is obscured by an overlay, verify shadow DOM context, or examine element state before interacting.

Args: session_id: Active session ID. selector: CSS selector of the element to inspect. frame_context: Iframe selector path. Use 'main' or omit for top-level. include_listeners: Detect inline event handlers (onclick, etc.). Default: false. include_children: Include child element summary. Default: true.

Process a downloaded file: convert format, rename, and move to destination.

Call this after a download completes. Handles format conversion (e.g., SpreadsheetML 2003 XML to CSV), filename pattern application, and file delivery to a target directory.

Args: session_id: Active session ID. source_format: Source file format. Use "auto" to detect from file contents. Known formats: spreadsheetml_2003, xls_binary, xlsx, csv. target_format: Target format to convert to (e.g., "csv"). Default: "csv". target_filename: Filename pattern with tokens: {MM}, {dd}, {yyyy}, {HH}, {mm}, {suggested}. Example: "Complete Enrollments Report {MM}.{dd}.{yyyy}.csv" target_directory: Destination directory. UNC paths supported (e.g., \server\share\path). guid: Specific download GUID to process. If omitted, processes the most recent completed download.

Return the complete structured history of a browser session.

Includes every action taken, every scout report (summarized), every network event captured, and the sequence of URLs visited. Use this data to compose botasaurus-driver scripts.

Args: session_id: Session ID (active or recently closed).

Control network monitoring for the current session.

Start monitoring before performing actions that trigger API calls or downloads, then query to see what was captured.

Args: session_id: Active session ID. command: start: begin capturing. stop: stop. query: return captured events. wait_for_download: block until download. url_pattern: Optional regex pattern to filter captured requests by URL. timeout_ms: For wait_for_download: maximum wait time. Default: 30000. capture_response_body: Whether to capture response bodies (adds overhead). Default: false. limit: Maximum number of events to return in a query response. Default: 100. offset: Number of matching events to skip before returning results. Default: 0.

Control video recording for the current browser session.

Records the browser screen using CDP screencast and encodes to MP4 or GIF. Requires ffmpeg for video encoding: install imageio-ffmpeg (pip install 'imageio-ffmpeg') or have ffmpeg on your system PATH. Without it, raw JPEG frames are saved instead.

Args: session_id: Active session ID. command: start: begin recording. stop: stop and encode video. status: check recording state. max_width: Maximum video width in pixels. Default: 1920. max_height: Maximum video height in pixels. Default: 1080. quality: JPEG frame quality (1-100). Default: 95. target_fps: Target frames per second (approximate). Default: 15. output_format: Output encoding format when stopping. "mp4" (default) or "gif". GIF uses palette-optimized encoding at 10fps/800px width for README-embeddable demos.

Close the browser session and release all resources.

Always call this when automation exploration is complete.

Args: session_id: Session ID to close.

Fetch a 2FA OTP code from Twilio SMS — call this AFTER clicking 'Send Code'.

Polls the Twilio Messages API until a new SMS matching app_keyword arrives, then extracts and returns the OTP code. Twilio credentials are read from .env and never exposed in tool responses.

Call this tool AFTER triggering the 2FA send in the browser. The baseline inbox state is captured at call time; Twilio delivery latency (2-10s) gives sufficient buffer before the first poll.

Args: app_keyword: Case-insensitive keyword to match in the SMS body. Use the site name, e.g. 'paycom', 'chase', 'google'. code_pattern: Regex to extract the OTP. Default: 6-digit number. Override for 8-digit or alphanumeric codes. timeout: Seconds to wait for the code before giving up. Default: 60.

Required .env entries: TWILIO_ACCOUNT_SID — Twilio Account SID TWILIO_AUTH_TOKEN — Twilio Auth Token TWILIO_PHONE_NUMBER — Digits-only recipient number (e.g. 14155551234)

Create or update a scheduled task for an exported SCOUT workflow.

Generates a platform-appropriate run script and registers the schedule with the OS task scheduler (Windows Task Scheduler, macOS launchd, or Linux cron).

Args: name: Workflow name. Must match .py inside workflow_dir. workflow_dir: Absolute path to the workflow directory (e.g., 'D:/Projects/app/workflows/enrollment'). schedule: Frequency — one of DAILY, WEEKLY, ONCE. time: Time to run in HH:MM 24-hour format (e.g., '06:45', '14:00'). days: Comma-separated day names for WEEKLY schedules (e.g., 'MON,WED,FRI'). Required when schedule is WEEKLY.

List all SCOUT scheduled tasks on this machine.

Returns all tasks registered with the OS task scheduler (Windows Task Scheduler, macOS launchd, or Linux cron) under the SCOUT namespace.

Delete a scheduled task from the OS task scheduler.

Removes the task from Windows Task Scheduler, macOS launchd, or Linux cron. Does not delete the workflow files — only the schedule.

Args: name: Name of the scheduled task to delete.

Return recent security events from the Scout security log.

Useful for auditing a session before exporting a workflow — if a session had injection attempts, that should inform whether the workflow is trustworthy.

Args: session_id: Filter to events from this session only. severity: Filter by severity level: 'info', 'warning', or 'critical'. limit: Maximum number of events to return. Default: 50.

Permit a single cross-origin navigation that was blocked by the navigation guard.

Only needed in extension mode when allowed_domains is set and the agent navigates to an unlisted domain. The guard never auto-permits — this tool requires explicit agent invocation.

Args: session_id: Active session ID. url: The URL to permit navigation to.

Fetch a web page and extract its content as clean markdown.

Lightweight alternative to the full Scout session flow. One tool call, content out. Uses HTTP by default with automatic stealth browser fallback for bot-protected pages.

Args: url: The page URL to fetch. query: Optional — extract only content relevant to this query. max_length: Optional — cap response length in characters. 0 = unlimited.