io.github.TickTockBent/charlotte

Manage Charlotte tool visibility. Lists available tool groups and their

Wait for a condition to be met on the page. Returns page representation when the condition is satisfied, or a TIMEOUT error.

Load a URL in the active page. Returns page representation after navigation. Default minimal detail includes landmarks, headings, and interactive element counts — use charlotte_find to locate specific elements, or pass detail: 'summary' to get the full element list.

Navigate back in browser history. Returns page representation after navigation.

Navigate forward in browser history. Returns page representation after navigation.

Reload the current page. Returns page representation after reload.

Handle a pending JavaScript dialog (alert, confirm, prompt, beforeunload). Accept or dismiss the dialog. Returns page representation after the dialog is resolved.

Serve a local directory as a static website and optionally watch for file changes. Navigates to the served URL and returns the page representation. File changes trigger automatic reloads and surface as reload_event on the next tool response.

Inject CSS or JavaScript into the current page for testing modifications without editing files. Returns the page representation with a delta showing changes.

Run accessibility and quality audits on the current page. Returns findings with severity levels and actionable recommendations.

Get cookies for the active page. Optionally filter by URL(s). Returns cookie name, value, domain, path, and flags.

Clear cookies from the browser. Optionally filter by name(s) to remove specific cookies. Without a filter, clears all cookies for the current page.

Set cookies on the active page. Cookies persist for subsequent navigations within matching domains.

Set extra HTTP headers for subsequent requests. Headers persist for all navigations on the active page.

Configure Charlotte runtime settings. Changes take effect immediately.

List all open browser tabs with their URLs, titles, and active status.

Open a new browser tab. Optionally navigate to a URL. The new tab becomes the active tab.

Switch to a different browser tab by its tab ID. Returns the page representation of the activated tab.

Close a browser tab by its ID. If the closed tab was active, switches to the first remaining tab.

Change the browser viewport dimensions. Use a device preset or specify custom width/height. Returns page representation at the new viewport size.

Configure network conditions for the active page. Set throttling presets, block URL patterns, or enable request logging.

Get current page state without performing any action. Use detail levels to control verbosity: "minimal" for landmarks, headings, and interactive element counts by landmark (use charlotte_find to get specific elements with actionable IDs, or observe({ detail: "summary" }) to see all elements), "summary" (default) for content summaries and full element list, "full" for all text content. Use view: "tree" for a compact structural outline (cheapest orientation tool), or view: "tree-labeled" to include labels on interactive elements (still much cheaper than minimal JSON, and shows which button/link/input is which).

Search for elements matching criteria. Filters interactive elements by text, role, type, or spatial proximity. Use the selector parameter to find DOM elements by CSS selector — this reaches elements not in the accessibility tree (custom widgets, non-semantic divs). Selector results return Charlotte element IDs usable with click, hover, drag, etc.

Capture a visual screenshot. Fallback for when structured representation isn't sufficient (complex visualizations, canvas elements, images). Use save: true to persist as a file artifact that can be referenced later.

List all saved screenshot artifacts. Returns metadata for each saved screenshot including ID, filename, page URL, and timestamp.

Retrieve a previously saved screenshot artifact by its ID. Returns the image data and metadata.

Delete a saved screenshot artifact by its ID. Removes the file from disk.

Compare current page state to a previous snapshot. Returns structural diff showing added, removed, moved, and changed elements.

Click an interactive element on the page. Returns full page representation after the click.

Click at specific page coordinates. Use when target elements are not in the accessibility tree (custom widgets, canvas, non-semantic interactive divs). Dispatches real CDP-level mouse events. Returns full page representation after the click.

Type text into an input element. Returns full page representation after typing.

Select an option in a select/dropdown element. Returns full page representation after selection.

Toggle a checkbox or switch element. Returns full page representation after toggle.

Submit a form. Can submit by form ID or by clicking its submit button. Returns full page representation after submission.

Scroll the page or a specific container. Returns full page representation after scrolling.

Hover over an element to trigger hover states. Returns full page representation after hover.

Drag an element to another element. Uses mouse primitives to simulate drag-and-drop. Returns full page representation after the drag.

Send keyboard input to the page or a specific element. Supports single key with modifiers, or a sequence of keys. Use for keyboard-driven UIs (games, terminals, code editors) and non-input elements with keydown listeners.

Set files on a file input element. Validates that files exist and that the target is a file input. Returns full page representation after upload.

Fill multiple form fields in a single call. Auto-detects element types (text input, select, checkbox, etc.) and applies the appropriate action. Returns a single page representation with delta covering all changes. All fields are validated up front before any field is mutated; if validation fails, no fields are changed. Note: if a field action fails mid-list (e.g. a handler throws after earlier fields succeeded), earlier fields remain applied.

Execute JavaScript in page context. Supports single expressions and multi-statement code. Returns the completion value of the last expression-statement.

Retrieve console messages from the active page. Returns messages at all severity levels (log, info, warning, error, debug, etc.) with timestamps. Useful for debugging JavaScript behavior.

Retrieve network request history from the active page. Returns all HTTP requests with method, status, resource type, and timestamps. Useful for debugging API calls and resource loading.