chrome-agent 0.1.0__py3-none-any.whl

chrome_agent/__init__.py

@@ -0,0 +1,5 @@
+"""chrome-agent: CLI tool for AI agents to observe and interact with Chrome via CDP."""
+
+from importlib.metadata import version
+
+__version__ = version("chrome-agent")

chrome_agent/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m chrome_agent"""
+
+from chrome_agent.cli import main
+
+main()

chrome_agent/browser.py

@@ -0,0 +1,190 @@
+"""Browser launcher with optional anti-detection fingerprinting.
+
+Launches a Playwright Chromium browser with CDP enabled. Optionally
+applies a fingerprint profile to make the browser appear as a real
+desktop browser.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+
+from playwright.async_api import Browser, Page, Playwright, async_playwright
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BrowserFingerprint:
+    """Browser fingerprint profile for anti-detection."""
+
+    user_agent: str
+    viewport: dict[str, int]
+    locale: str
+    timezone: str
+    platform: str
+    vendor: str
+
+
+@dataclass
+class BrowserSession:
+    """Handle to a launched browser session."""
+
+    playwright: Playwright
+    browser: Browser
+    page: Page
+
+
+async def load_fingerprint(*, path: str) -> BrowserFingerprint:
+    """Load a browser fingerprint profile from a JSON file.
+
+    Expected JSON schema:
+        {
+            "userAgent": "...",
+            "platform": "...",
+            "vendor": "...",
+            "language": "en-US",
+            "timezone": "America/Chicago",
+            "viewport": {"width": 1920, "height": 1080}
+        }
+    """
+    with open(path, "r") as f:
+        data = json.load(f)
+
+    return BrowserFingerprint(
+        user_agent=data["userAgent"],
+        viewport=data["viewport"],
+        locale=data["language"],
+        timezone=data["timezone"],
+        platform=data["platform"],
+        vendor=data["vendor"],
+    )
+
+
+async def launch_browser(
+    *,
+    port: int = 9222,
+    fingerprint: BrowserFingerprint | None = None,
+    headless: bool = False,
+    wm_class: str = "chrome-agent",
+    pin_to_desktop: bool = True,
+) -> BrowserSession:
+    """Launch a Chromium browser with CDP enabled.
+
+    Args:
+        port: CDP remote debugging port.
+        fingerprint: Optional fingerprint for anti-detection. If None,
+            launches a clean browser with no spoofing.
+        headless: Run in headless mode.
+        wm_class: X11 window class name (for desktop pinning).
+        pin_to_desktop: Move browser window to the launching terminal's
+            virtual desktop. Default True. Linux/X11 only, requires
+            xdotool -- silently skipped on other platforms.
+    """
+    playwright = await async_playwright().start()
+
+    launch_args = [
+        "--disable-blink-features=AutomationControlled",
+        f"--remote-debugging-port={port}",
+        f"--class={wm_class}",
+    ]
+
+    browser = await playwright.chromium.launch(
+        headless=headless,
+        args=launch_args,
+    )
+
+    # Build context options
+    context_kwargs = {}
+    if fingerprint:
+        context_kwargs.update(
+            user_agent=fingerprint.user_agent,
+            viewport=fingerprint.viewport,
+            locale=fingerprint.locale,
+            timezone_id=fingerprint.timezone,
+        )
+
+    context = await browser.new_context(**context_kwargs)
+
+    # Apply anti-detection init script if fingerprinted
+    if fingerprint:
+        await context.add_init_script(f"""
+            Object.defineProperty(navigator, 'webdriver', {{
+                get: () => false
+            }});
+
+            Object.defineProperty(navigator, 'platform', {{
+                get: () => '{fingerprint.platform}'
+            }});
+
+            Object.defineProperty(navigator, 'vendor', {{
+                get: () => '{fingerprint.vendor}'
+            }});
+
+            window.chrome = {{
+                runtime: {{}},
+                app: {{}}
+            }};
+        """)
+
+    page = await context.new_page()
+
+    session = BrowserSession(
+        playwright=playwright,
+        browser=browser,
+        page=page,
+    )
+
+    if pin_to_desktop:
+        await _move_to_launching_desktop(wm_class=wm_class)
+
+    return session
+
+
+async def _move_to_launching_desktop(*, wm_class: str) -> None:
+    """Move the browser window to the terminal's virtual desktop.
+
+    Linux/X11 only. Requires xdotool. Silently does nothing if
+    xdotool is unavailable or on non-X11 systems.
+    """
+    try:
+        # Determine which desktop our terminal is on
+        window_id = os.environ.get("WINDOWID", "")
+        if window_id:
+            result = subprocess.run(
+                ["xdotool", "get_desktop_for_window", window_id],
+                capture_output=True, text=True,
+            )
+            desktop = result.stdout.strip()
+        else:
+            result = subprocess.run(
+                ["xdotool", "get_desktop"],
+                capture_output=True, text=True,
+            )
+            desktop = result.stdout.strip()
+
+        if not desktop:
+            return
+
+        # Wait for the browser window to appear
+        await asyncio.sleep(0.5)
+
+        # Find our browser windows by the custom WM_CLASS
+        result = subprocess.run(
+            ["xdotool", "search", "--class", wm_class],
+            capture_output=True, text=True,
+        )
+        for wid in result.stdout.strip().split("\n"):
+            if wid.strip():
+                subprocess.run(
+                    ["xdotool", "set_desktop_for_window", wid.strip(), desktop],
+                )
+
+        logger.info("Moved browser window(s) to desktop %s", desktop)
+    except FileNotFoundError:
+        logger.debug("xdotool not available -- skipping desktop move")
+    except Exception as e:
+        logger.debug("Could not move browser to desktop: %s", e)

chrome_agent/cli.py

@@ -0,0 +1,279 @@
+"""CLI entry point for chrome-agent.
+
+Usage: chrome-agent [--port PORT] <command> [args...]
+
+Single entry point with flat command dispatch. The --port flag is global
+and parsed before the command name.
+"""
+
+import asyncio
+import sys
+
+from .commands import (
+    cmd_back,
+    cmd_check,
+    cmd_click,
+    cmd_clickxy,
+    cmd_close,
+    cmd_cookies,
+    cmd_element,
+    cmd_eval,
+    cmd_fill,
+    cmd_find,
+    cmd_forward,
+    cmd_hover,
+    cmd_html,
+    cmd_navigate,
+    cmd_press,
+    cmd_reload,
+    cmd_screenshot,
+    cmd_scroll,
+    cmd_select,
+    cmd_snapshot,
+    cmd_tabs,
+    cmd_text,
+    cmd_type,
+    cmd_uncheck,
+    cmd_url,
+    cmd_value,
+    cmd_viewport,
+    cmd_wait,
+)
+from .connection import check_cdp_port, connect, disconnect
+from .errors import ChromeAgentError
+
+# Default CDP port
+DEFAULT_PORT = 9222
+
+# Command registry: name -> (func, nargs, description)
+# nargs: 0 = no args, 1 = one required arg, 2 = two required args, -1 = optional args
+COMMANDS = {
+    # Observe
+    "url": (cmd_url, 0, "Print current URL and title"),
+    "screenshot": (cmd_screenshot, -1, "Save screenshot [path]"),
+    "snapshot": (cmd_snapshot, 0, "Print accessibility tree"),
+    "text": (cmd_text, 0, "Print page visible text"),
+    "html": (cmd_html, -1, "Print page HTML [selector]"),
+    "element": (cmd_element, 1, "Inspect element <selector>"),
+    "find": (cmd_find, 1, "Find elements <selector>"),
+    "value": (cmd_value, 1, "Get input value <selector>"),
+    "eval": (cmd_eval, 1, "Execute JavaScript <code>"),
+    "cookies": (cmd_cookies, 0, "Dump cookies"),
+    "tabs": (cmd_tabs, 0, "List open pages"),
+    "wait": (cmd_wait, 1, "Wait for <selector|ms|load>"),
+    # Navigate
+    "navigate": (cmd_navigate, 1, "Go to <url>"),
+    "back": (cmd_back, 0, "Browser back"),
+    "forward": (cmd_forward, 0, "Browser forward"),
+    "reload": (cmd_reload, 0, "Reload page"),
+    # Interact
+    "click": (cmd_click, 1, "Click <selector>"),
+    "clickxy": (cmd_clickxy, 2, "Click at <x> <y>"),
+    "fill": (cmd_fill, 2, "Fill <selector> <value>"),
+    "type": (cmd_type, 2, "Type into <selector> <text>"),
+    "press": (cmd_press, 1, "Press key <Enter|Escape|Tab|...>"),
+    "select": (cmd_select, 2, "Select option <selector> <value>"),
+    "check": (cmd_check, 1, "Check checkbox <selector>"),
+    "uncheck": (cmd_uncheck, 1, "Uncheck checkbox <selector>"),
+    "hover": (cmd_hover, 1, "Hover over <selector>"),
+    "scroll": (cmd_scroll, 1, "Scroll <selector|up|down>"),
+    # Meta
+    "close": (cmd_close, 0, "Close current page"),
+    "viewport": (cmd_viewport, 2, "Resize viewport <width> <height>"),
+}
+
+# Commands that don't need a CDP connection
+LOCAL_COMMANDS = {"status", "launch", "help"}
+
+
+def _print_help() -> None:
+    """Print command reference."""
+    print("chrome-agent -- CLI for AI agents to observe and interact with Chrome\n")
+    print("Usage: chrome-agent [--port PORT] <command> [args...]\n")
+    print("Commands:")
+    print(f"  {'status':12s} Check if browser is running on CDP port")
+    print(f"  {'launch':12s} Launch a browser with CDP enabled [--fingerprint PATH] [--headless] [--no-pin-desktop]")
+    print(f"  {'help':12s} Print this help message")
+    print()
+    for name, (_, _, desc) in COMMANDS.items():
+        print(f"  {name:12s} {desc}")
+
+
+def _parse_global_args(argv: list[str]) -> tuple[int, list[str]]:
+    """Extract --port from argv, return (port, remaining_args)."""
+    port = DEFAULT_PORT
+    remaining = []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--port" and i + 1 < len(argv):
+            try:
+                port = int(argv[i + 1])
+            except ValueError:
+                print(f"ERROR: Invalid port: {argv[i + 1]}")
+                sys.exit(1)
+            i += 2
+        else:
+            remaining.append(argv[i])
+            i += 1
+    return port, remaining
+
+
+async def _run_command(*, port: int, cmd_name: str, args: list[str]) -> None:
+    """Connect to browser, run a command, disconnect."""
+    func, expected_args, _ = COMMANDS[cmd_name]
+
+    # Validate argument count
+    if expected_args >= 0 and len(args) < expected_args:
+        print(f"Command '{cmd_name}' requires {expected_args} argument(s)")
+        sys.exit(1)
+
+    pw, browser, page = await connect(port=port)
+    try:
+        # Dispatch based on argument pattern
+        if cmd_name == "tabs":
+            # cmd_tabs needs both page and browser
+            await func(page=page, browser=browser)
+        elif expected_args == 0:
+            await func(page=page)
+        elif expected_args == -1:
+            # Optional args
+            if cmd_name == "screenshot" and args:
+                await func(page=page, path=args[0])
+            elif cmd_name == "html" and args:
+                await func(page=page, selector=args[0])
+            else:
+                await func(page=page)
+        elif expected_args == 1:
+            # Single required arg -- map to the right parameter name
+            arg = args[0]
+            if cmd_name in ("element", "find", "value", "click", "check",
+                            "uncheck", "hover"):
+                await func(page=page, selector=arg)
+            elif cmd_name == "eval":
+                await func(page=page, js_code=arg)
+            elif cmd_name == "navigate":
+                await func(page=page, url=arg)
+            elif cmd_name == "wait":
+                await func(page=page, target=arg)
+            elif cmd_name == "press":
+                await func(page=page, key=arg)
+            elif cmd_name == "scroll":
+                await func(page=page, target=arg)
+            else:
+                await func(page=page)
+        elif expected_args == 2:
+            # Two required args -- second arg may be multi-word (join remaining)
+            arg1 = args[0]
+            arg2 = " ".join(args[1:])
+            if cmd_name == "clickxy":
+                await func(page=page, x=float(arg1), y=float(arg2))
+            elif cmd_name == "fill":
+                await func(page=page, selector=arg1, value=arg2)
+            elif cmd_name == "type":
+                await func(page=page, selector=arg1, text=arg2)
+            elif cmd_name == "select":
+                await func(page=page, selector=arg1, value=arg2)
+            elif cmd_name == "viewport":
+                await func(page=page, width=int(arg1), height=int(arg2))
+            else:
+                await func(page=page)
+    finally:
+        await disconnect(pw=pw)
+
+
+async def _run_status(*, port: int) -> None:
+    """Check if a browser is running on the CDP port."""
+    status = check_cdp_port(port=port)
+    if status.listening:
+        print(f"Browser running on port {port}")
+        if status.browser_version:
+            print(f"  Version: {status.browser_version}")
+        if status.page_url:
+            print(f"  URL:     {status.page_url}")
+        if status.page_title:
+            print(f"  Title:   {status.page_title}")
+    else:
+        print(f"No browser running on port {port}")
+
+
+async def _run_launch(*, port: int, args: list[str]) -> None:
+    """Launch a browser with CDP enabled."""
+    # Import here to avoid circular imports and loading browser module
+    # when it's not needed
+    from .browser import launch_browser, load_fingerprint
+
+    # Parse launch-specific flags
+    fingerprint_path = None
+    headless = False
+    pin_desktop = True  # Default: pin browser to launching terminal's desktop
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--fingerprint" and i + 1 < len(args):
+            fingerprint_path = args[i + 1]
+            i += 2
+        elif args[i] == "--headless":
+            headless = True
+            i += 1
+        elif args[i] == "--no-pin-desktop":
+            pin_desktop = False
+            i += 1
+        else:
+            print(f"Unknown launch option: {args[i]}")
+            sys.exit(1)
+
+    # Load fingerprint if specified
+    fingerprint = None
+    if fingerprint_path:
+        fingerprint = await load_fingerprint(path=fingerprint_path)
+
+    session = await launch_browser(
+        port=port,
+        fingerprint=fingerprint,
+        headless=headless,
+        pin_to_desktop=pin_desktop,
+    )
+
+    print(f"Browser launched on CDP port {port}")
+    print("Press Ctrl+C to close.")
+
+    # Keep alive until interrupted
+    try:
+        while True:
+            await asyncio.sleep(60)
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    finally:
+        await session.browser.close()
+        await session.playwright.stop()
+        print("\nBrowser closed.")
+
+
+def main() -> None:
+    """CLI entry point."""
+    port, remaining = _parse_global_args(argv=sys.argv[1:])
+
+    if not remaining or remaining[0] in ("-h", "--help", "help"):
+        _print_help()
+        sys.exit(0)
+
+    cmd_name = remaining[0]
+    args = remaining[1:]
+
+    if cmd_name == "status":
+        asyncio.run(_run_status(port=port))
+    elif cmd_name == "launch":
+        asyncio.run(_run_launch(port=port, args=args))
+    elif cmd_name in COMMANDS:
+        try:
+            asyncio.run(_run_command(port=port, cmd_name=cmd_name, args=args))
+        except ChromeAgentError as e:
+            print(f"ERROR: {e}")
+            sys.exit(1)
+        except Exception as e:
+            print(f"ERROR: {e}")
+            sys.exit(1)
+    else:
+        print(f"Unknown command: {cmd_name}")
+        print("Run 'chrome-agent help' to see available commands")
+        sys.exit(1)

chrome_agent/commands.py

@@ -0,0 +1,370 @@
+"""Browser observation, navigation, and interaction commands.
+
+Each command is an async function that accepts a Playwright Page (and
+optionally Browser) as its first argument. Commands print their results
+to stdout and raise exceptions on failure. The CLI layer handles
+connection lifecycle and error presentation.
+"""
+
+import json
+
+from playwright.async_api import Browser, Page
+
+from .errors import ElementNotFoundError
+
+
+# ---------------------------------------------------------------------------
+# Observation commands
+# ---------------------------------------------------------------------------
+
+
+async def cmd_url(*, page: Page) -> None:
+    """Print current URL and page title."""
+    print(f"URL:   {page.url}")
+    print(f"Title: {await page.title()}")
+
+
+async def cmd_screenshot(*, page: Page, path: str = "/tmp/cdp-screenshot.png") -> None:
+    """Save a screenshot of the current page."""
+    await page.screenshot(path=path)
+    print(f"Screenshot saved: {path}")
+
+
+async def cmd_snapshot(*, page: Page) -> None:
+    """Print the accessibility tree of the current page (ARIA snapshot)."""
+    snapshot = await page.locator(":root").aria_snapshot()
+    if snapshot:
+        print(snapshot)
+    else:
+        print("(empty accessibility tree)")
+
+
+async def cmd_text(*, page: Page) -> None:
+    """Print visible text content of the page."""
+    text = await page.inner_text("body")
+    if len(text) > 5000:
+        print(text[:5000])
+        print(f"\n... (truncated, {len(text)} total chars)")
+    else:
+        print(text)
+
+
+async def cmd_html(*, page: Page, selector: str | None = None) -> None:
+    """Print page HTML source, or a specific element's outerHTML."""
+    if selector:
+        el = page.locator(selector).first
+        if await el.count() > 0:
+            html = await el.evaluate("el => el.outerHTML")
+            print(html)
+        else:
+            raise ElementNotFoundError(selector=selector)
+    else:
+        html = await page.content()
+        if len(html) > 10000:
+            print(html[:10000])
+            print(f"\n... (truncated, {len(html)} total chars)")
+        else:
+            print(html)
+
+
+async def cmd_element(*, page: Page, selector: str) -> None:
+    """Print detailed info about a specific element."""
+    loc = page.locator(selector).first
+
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+
+    info = await loc.evaluate("""el => {
+        const cs = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        const attrs = {};
+        for (const a of el.attributes) attrs[a.name] = a.value;
+        return {
+            tag: el.tagName,
+            id: el.id,
+            text: el.innerText?.substring(0, 200) || '',
+            value: el.value || null,
+            type: el.type || null,
+            visible: el.offsetParent !== null || cs.display !== 'none',
+            display: cs.display,
+            visibility: cs.visibility,
+            opacity: cs.opacity,
+            dimensions: { width: rect.width, height: rect.height },
+            position: { x: Math.round(rect.x), y: Math.round(rect.y) },
+            inViewport: rect.top >= 0 && rect.left >= 0 &&
+                        rect.bottom <= window.innerHeight &&
+                        rect.right <= window.innerWidth,
+            disabled: el.disabled || false,
+            checked: el.checked ?? null,
+            href: el.href || null,
+            attributes: attrs,
+        };
+    }""")
+
+    print(f"Selector:    {selector}")
+    print(f"Tag:         {info['tag']}")
+    if info["type"]:
+        print(f"Type:        {info['type']}")
+    if info["id"]:
+        print(f"ID:          {info['id']}")
+    print(f"Text:        {info['text'][:100] if info['text'] else '(empty)'}")
+    if info["value"] is not None:
+        print(f"Value:       {info['value']}")
+    print(f"Visible:     {info['visible']}")
+    print(f"Display:     {info['display']}")
+    print(f"Visibility:  {info['visibility']}")
+    print(f"Opacity:     {info['opacity']}")
+    print(f"Dimensions:  {info['dimensions']['width']:.0f} x {info['dimensions']['height']:.0f}")
+    print(f"Position:    ({info['position']['x']}, {info['position']['y']})")
+    print(f"In viewport: {info['inViewport']}")
+    if info["disabled"]:
+        print(f"Disabled:    {info['disabled']}")
+    if info["checked"] is not None:
+        print(f"Checked:     {info['checked']}")
+    if info["href"]:
+        print(f"Href:        {info['href']}")
+    if info["attributes"]:
+        print(f"Attributes:  {json.dumps(info['attributes'], indent=2)}")
+
+
+async def cmd_find(*, page: Page, selector: str) -> None:
+    """Count and summarize elements matching a selector."""
+    loc = page.locator(selector)
+    count = await loc.count()
+
+    print(f"Selector: {selector}")
+    print(f"Count:    {count}")
+
+    for i in range(min(count, 20)):
+        item = loc.nth(i)
+        summary = await item.evaluate("""el => ({
+            tag: el.tagName,
+            text: (el.innerText || '').substring(0, 80),
+            visible: el.offsetParent !== null,
+            id: el.id || null,
+            cls: el.className?.substring?.(0, 60) || null,
+        })""")
+        vis = "visible" if summary["visible"] else "hidden"
+        text = summary["text"].replace("\n", " ").strip()[:60]
+        ident = summary["id"] or summary["cls"] or ""
+        print(f"  [{i}] <{summary['tag']}> {vis} | {ident} | {text}")
+
+    if count > 20:
+        print(f"  ... ({count - 20} more)")
+
+
+async def cmd_value(*, page: Page, selector: str) -> None:
+    """Get the current value of an input element."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    val = await loc.input_value()
+    print(val)
+
+
+async def cmd_eval(*, page: Page, js_code: str) -> None:
+    """Execute arbitrary JavaScript and print the result."""
+    result = await page.evaluate(js_code)
+    if isinstance(result, (dict, list)):
+        print(json.dumps(result, indent=2))
+    else:
+        print(result)
+
+
+async def cmd_cookies(*, page: Page) -> None:
+    """Dump all cookies for the current page."""
+    context = page.context
+    cookies = await context.cookies()
+    for c in cookies:
+        exp = c.get("expires", -1)
+        exp_str = f"expires={exp}" if exp > 0 else "session"
+        print(
+            f"  {c['name']}={c['value'][:40]}"
+            f"{'...' if len(c['value']) > 40 else ''}"
+            f"  ({c['domain']}, {exp_str})"
+        )
+    if not cookies:
+        print("(no cookies)")
+
+
+async def cmd_tabs(*, page: Page, browser: Browser) -> None:
+    """List all open pages/tabs in the browser."""
+    for ctx in browser.contexts:
+        for i, p in enumerate(ctx.pages):
+            marker = " *" if p == page else ""
+            print(f"  [{i}] {p.url}")
+            print(f"       {await p.title()}{marker}")
+
+
+async def cmd_wait(*, page: Page, target: str) -> None:
+    """Wait for a selector, milliseconds, or load state."""
+    if target.isdigit():
+        ms = int(target)
+        print(f"Waiting {ms}ms...")
+        await page.wait_for_timeout(ms)
+        print("Done")
+    elif target in ("load", "domcontentloaded", "networkidle"):
+        print(f"Waiting for {target}...")
+        await page.wait_for_load_state(target)
+        print("Done")
+    else:
+        print(f"Waiting for selector: {target}")
+        await page.locator(target).first.wait_for(timeout=30000)
+        print("Found")
+
+
+# ---------------------------------------------------------------------------
+# Navigation commands
+# ---------------------------------------------------------------------------
+
+
+async def cmd_navigate(*, page: Page, url: str) -> None:
+    """Navigate to a URL and wait for load."""
+    response = await page.goto(url)
+    status = response.status if response else "unknown"
+    print(f"Navigated to: {page.url}")
+    print(f"Status: {status}")
+    print(f"Title: {await page.title()}")
+
+
+async def cmd_back(*, page: Page) -> None:
+    """Go back in browser history."""
+    await page.go_back()
+    print(f"URL: {page.url}")
+
+
+async def cmd_forward(*, page: Page) -> None:
+    """Go forward in browser history."""
+    await page.go_forward()
+    print(f"URL: {page.url}")
+
+
+async def cmd_reload(*, page: Page) -> None:
+    """Reload the current page."""
+    await page.reload()
+    print(f"Reloaded: {page.url}")
+
+
+# ---------------------------------------------------------------------------
+# Interaction commands
+# ---------------------------------------------------------------------------
+
+
+async def cmd_click(*, page: Page, selector: str) -> None:
+    """Click an element. Falls back to JS click if not actionable."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+
+    try:
+        await loc.click(timeout=5000)
+        print(f"Clicked: {selector}")
+    except Exception:
+        # Fallback to JS click for hidden/obscured elements
+        try:
+            await loc.evaluate("el => el.click()")
+            print(f"JS-clicked: {selector} (element was not actionable)")
+        except Exception as e:
+            print(f"ERROR clicking {selector}: {e}")
+
+
+async def cmd_clickxy(*, page: Page, x: float, y: float) -> None:
+    """Click at page coordinates."""
+    await page.mouse.click(x=x, y=y)
+    print(f"Clicked at ({x}, {y})")
+
+
+async def cmd_fill(*, page: Page, selector: str, value: str) -> None:
+    """Fill a form field (clears first, dispatches events)."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.fill(value)
+    print(f"Filled {selector} with: {value}")
+
+
+async def cmd_type(*, page: Page, selector: str, text: str) -> None:
+    """Type text character by character into an element."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.type(text)
+    print(f"Typed into {selector}: {text}")
+
+
+async def cmd_press(*, page: Page, key: str) -> None:
+    """Press a keyboard key (Enter, Escape, Tab, etc.)."""
+    await page.keyboard.press(key)
+    print(f"Pressed: {key}")
+
+
+async def cmd_select(*, page: Page, selector: str, value: str) -> None:
+    """Select an option from a dropdown."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.select_option(value=value)
+    print(f"Selected {value} in {selector}")
+
+
+async def cmd_check(*, page: Page, selector: str) -> None:
+    """Check a checkbox."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.check()
+    print(f"Checked: {selector}")
+
+
+async def cmd_uncheck(*, page: Page, selector: str) -> None:
+    """Uncheck a checkbox."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.uncheck()
+    print(f"Unchecked: {selector}")
+
+
+async def cmd_hover(*, page: Page, selector: str) -> None:
+    """Hover over an element."""
+    loc = page.locator(selector).first
+    if await loc.count() == 0:
+        raise ElementNotFoundError(selector=selector)
+    await loc.hover()
+    print(f"Hovering: {selector}")
+
+
+async def cmd_scroll(*, page: Page, target: str) -> None:
+    """Scroll to an element, or scroll the page (up/down)."""
+    if target == "up":
+        await page.mouse.wheel(delta_x=0, delta_y=-500)
+        print("Scrolled up")
+    elif target == "down":
+        await page.mouse.wheel(delta_x=0, delta_y=500)
+        print("Scrolled down")
+    else:
+        loc = page.locator(target).first
+        if await loc.count() == 0:
+            raise ElementNotFoundError(selector=target)
+        await loc.scroll_into_view_if_needed()
+        print(f"Scrolled to: {target}")
+
+
+# ---------------------------------------------------------------------------
+# Meta commands (operate on page/viewport, not elements)
+# ---------------------------------------------------------------------------
+
+
+async def cmd_close(*, page: Page) -> None:
+    """Close the current page."""
+    url = page.url
+    await page.close()
+    print(f"Closed: {url}")
+
+
+async def cmd_viewport(*, page: Page, width: int, height: int) -> None:
+    """Resize the viewport."""
+    await page.set_viewport_size({"width": width, "height": height})
+    print(f"Viewport set to {width}x{height}")
+
+

chrome_agent/connection.py

@@ -0,0 +1,109 @@
+"""CDP connection management.
+
+Handles connecting to and disconnecting from a Chrome browser via the
+Chrome DevTools Protocol. Also provides port status checking using only
+stdlib (no Playwright needed for status).
+"""
+
+import json
+import os
+import socket
+import urllib.request
+from dataclasses import dataclass
+
+from playwright.async_api import Playwright, async_playwright
+
+from .errors import BrowserConnectionError, NoPageError
+
+# Suppress Node.js deprecation warnings from Playwright internals.
+# This must be set before Playwright spawns its Node.js subprocess.
+os.environ.setdefault("NODE_OPTIONS", "--no-deprecation")
+
+
+@dataclass
+class PortStatus:
+    """Result of checking whether a CDP port is active."""
+
+    listening: bool
+    browser_version: str | None = None
+    page_url: str | None = None
+    page_title: str | None = None
+
+
+def check_cdp_port(*, port: int = 9222) -> PortStatus:
+    """Check if a browser is listening on the CDP port.
+
+    Uses stdlib only (socket + urllib) -- no Playwright dependency.
+    This is a synchronous function since it only does simple HTTP.
+    """
+    # Quick socket check first
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(1)
+    try:
+        result = sock.connect_ex(("localhost", port))
+        if result != 0:
+            return PortStatus(listening=False)
+    finally:
+        sock.close()
+
+    # Port is open -- try to get browser version
+    browser_version = None
+    try:
+        req = urllib.request.Request(f"http://localhost:{port}/json/version")
+        with urllib.request.urlopen(req, timeout=2) as resp:
+            data = json.loads(resp.read())
+            browser_version = data.get("Browser")
+    except Exception:
+        pass
+
+    # Try to get the first page's URL and title
+    page_url = None
+    page_title = None
+    try:
+        req = urllib.request.Request(f"http://localhost:{port}/json")
+        with urllib.request.urlopen(req, timeout=2) as resp:
+            pages = json.loads(resp.read())
+            if pages:
+                page_url = pages[0].get("url")
+                page_title = pages[0].get("title")
+    except Exception:
+        pass
+
+    return PortStatus(
+        listening=True,
+        browser_version=browser_version,
+        page_url=page_url,
+        page_title=page_title,
+    )
+
+
+async def connect(*, port: int = 9222):
+    """Connect to a running browser via CDP.
+
+    Returns (playwright, browser, page) tuple. The caller is responsible
+    for calling disconnect() when done.
+
+    Raises BrowserConnectionError if no browser is listening.
+    Raises NoPageError if the browser has no open pages.
+    """
+    pw = await async_playwright().start()
+
+    cdp_url = f"http://localhost:{port}"
+    try:
+        browser = await pw.chromium.connect_over_cdp(cdp_url)
+    except Exception as exc:
+        await pw.stop()
+        raise BrowserConnectionError(port=port) from exc
+
+    contexts = browser.contexts
+    if not contexts or not contexts[0].pages:
+        await pw.stop()
+        raise NoPageError()
+
+    page = contexts[0].pages[0]
+    return pw, browser, page
+
+
+async def disconnect(*, pw: Playwright) -> None:
+    """Clean up a Playwright connection."""
+    await pw.stop()

chrome_agent/errors.py

@@ -0,0 +1,45 @@
+"""Custom exceptions for chrome-agent.
+
+Each exception produces an actionable error message that tells the agent
+what went wrong and what to do about it.
+"""
+
+
+class ChromeAgentError(Exception):
+    """Base exception for all chrome-agent errors."""
+
+
+class BrowserConnectionError(ChromeAgentError):
+    """Cannot connect to a browser via CDP.
+
+    Raised when no browser is listening on the expected CDP port.
+    """
+
+    def __init__(self, *, port: int = 9222):
+        super().__init__(
+            f"No browser running on port {port}. "
+            f"Start one with: chrome-agent launch"
+        )
+        self.port = port
+
+
+class NoPageError(ChromeAgentError):
+    """Browser is connected but has no open pages.
+
+    This typically happens when the browser was just launched and hasn't
+    navigated anywhere, or when all tabs have been closed.
+    """
+
+    def __init__(self):
+        super().__init__("Browser is running but has no open pages.")
+
+
+class ElementNotFoundError(ChromeAgentError):
+    """No element matched the given selector.
+
+    Raised by commands that require an element to exist (click, fill, etc.).
+    """
+
+    def __init__(self, *, selector: str):
+        super().__init__(f"No element found for selector: {selector}")
+        self.selector = selector

chrome_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: chrome-agent
+Version: 0.1.0
+Summary: CLI tool for AI agents to observe and interact with Chrome via CDP
+Keywords: chrome,cdp,devtools,browser,automation,agent
+Author: Corey Gallon
+Author-email: Corey Gallon <366332+captivus@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Dist: playwright>=1.50.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/captivus/chrome-agent
+Project-URL: Repository, https://github.com/captivus/chrome-agent
+Project-URL: Issues, https://github.com/captivus/chrome-agent/issues
+Description-Content-Type: text/markdown
+
+# chrome-agent
+
+[![PyPI version](https://img.shields.io/pypi/v/chrome-agent)](https://pypi.org/project/chrome-agent/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chrome-agent)](https://pypi.org/project/chrome-agent/)
+[![License](https://img.shields.io/pypi/l/chrome-agent)](https://github.com/captivus/chrome-agent/blob/main/LICENSE)
+
+A CLI tool that gives AI coding agents the ability to observe and interact with Chrome browsers.
+
+Built as a replacement for browser MCP tools. Faster, lower token overhead, and supports something MCP tools can't do: multiple agents sharing the same browser instance.
+
+## Why this exists
+
+AI coding agents need to see and interact with browsers -- to test their code, debug automation, inspect page state. The standard approach (browser MCP tools) uses a persistent server with protocol negotiation and verbose response formatting. `chrome-agent` takes a different approach: each command is a standalone CLI call that connects to Chrome via the DevTools Protocol, does one thing, and disconnects. No server, no session state, no bloat.
+
+This also enables a workflow that MCP tools can't support: one process drives the browser (your automation code) while a separate agent observes the same browser to diagnose issues and improve the code.
+
+## Installation
+
+```bash
+uv tool install chrome-agent
+playwright install chromium
+```
+
+Or add to a project:
+
+```bash
+uv add chrome-agent
+uv run playwright install chromium
+```
+
+## Two ways to use it
+
+### Drive mode -- you control the browser
+
+Launch a browser and interact with it directly. This is the MCP replacement use case.
+
+```bash
+chrome-agent launch &
+chrome-agent navigate "https://example.com"
+chrome-agent text                        # Read page content
+chrome-agent element "h1"                # Inspect an element
+chrome-agent fill "#search" "query"      # Fill a form field
+chrome-agent click "#submit"             # Click a button
+chrome-agent screenshot /tmp/page.png    # Capture the screen
+```
+
+### Attach mode -- observe a running browser
+
+Your automation code launches a browser with `--remote-debugging-port=9222`. You connect to observe what the code is doing, diagnose failures, and figure out what to change.
+
+```bash
+chrome-agent status                      # Is the browser running?
+chrome-agent url                         # Where is it?
+chrome-agent element "#submit-btn"       # Why can't the code click this?
+chrome-agent eval "document.querySelectorAll('.error').length"
+chrome-agent screenshot                  # What does it look like?
+```
+
+The feedback loop: **write code -> run it -> observe the browser -> diagnose -> modify code -> repeat.**
+
+## Commands
+
+```
+chrome-agent [--port PORT] <command> [args...]
+```
+
+### Check browser status
+
+```
+status                Check if a browser is running on the CDP port
+launch                Launch a browser with CDP enabled
+                      [--fingerprint PATH] [--headless] [--no-pin-desktop]
+help                  Print command reference
+```
+
+### Observe (read-only, always safe)
+
+```
+url                   Print current URL and page title
+screenshot [path]     Save a screenshot (default: /tmp/cdp-screenshot.png)
+snapshot              Print the ARIA accessibility tree
+text                  Print visible text content
+html [selector]       Print page HTML or a specific element's HTML
+element <selector>    Detailed element inspection (visibility, dimensions,
+                      attributes, position, disabled state)
+find <selector>       Count and list all matching elements
+value <selector>      Get an input element's current value
+eval <code>           Execute JavaScript and print the result
+cookies               List all cookies
+tabs                  List all open tabs/pages
+wait <target>         Wait for a selector, milliseconds, or load state
+```
+
+### Navigate
+
+```
+navigate <url>        Go to a URL
+back                  Browser back
+forward               Browser forward
+reload                Reload the page
+```
+
+### Interact
+
+```
+click <selector>      Click an element (JS fallback for hidden elements)
+fill <selector> <val> Fill a form field (clears first)
+type <selector> <txt> Type text character by character
+press <key>           Press a keyboard key (Enter, Escape, Tab, etc.)
+select <sel> <value>  Select a dropdown option
+check <selector>      Check a checkbox
+uncheck <selector>    Uncheck a checkbox
+hover <selector>      Hover over an element
+scroll <target>       Scroll to element, or scroll up/down
+clickxy <x> <y>       Click at page coordinates
+close                 Close the current page
+viewport <w> <h>      Resize the viewport
+```
+
+## For AI agents
+
+The primary user of this tool is an AI coding agent, not a human. See [INSTRUCTIONS.md](INSTRUCTIONS.md) for comprehensive agent instructions covering:
+
+- Drive mode vs attach mode mental model
+- Safety rules for shared browser access
+- The development feedback loop
+- When to observe vs intervene
+- Command recipes for common tasks
+- Failure modes and recovery
+
+Include the contents of `INSTRUCTIONS.md` in your project's `CLAUDE.md` or agent instructions file.
+
+## Browser fingerprinting (optional)
+
+For sites that detect automated browsers, launch with a fingerprint profile:
+
+```bash
+chrome-agent launch --fingerprint path/to/fingerprint.json
+```
+
+The fingerprint JSON overrides the browser's user agent, viewport, locale, timezone, and platform to match a real desktop browser:
+
+```json
+{
+    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) ...",
+    "platform": "Linux x86_64",
+    "vendor": "Google Inc.",
+    "language": "en-US",
+    "timezone": "America/Chicago",
+    "viewport": {"width": 1920, "height": 1080}
+}
+```
+
+Without `--fingerprint`, the browser launches with default Chromium settings.
+
+## Requirements
+
+- Python >= 3.11
+- Playwright >= 1.50.0
+- Chromium (installed via `playwright install chromium`)
+- Linux with xdotool (optional, for virtual desktop pinning)
+
+## License
+
+MIT

chrome_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+chrome_agent/__init__.py,sha256=_uI9RMpIIZMyy7AL0Ud2LDClQNzgBUqCJNObUp70wRw,167
+chrome_agent/__main__.py,sha256=xriXccBgzmz1dA1XjCF0j5oFK86n5XWehF55sfWl62g,90
+chrome_agent/browser.py,sha256=Bd3VAt77vkVxe7Yt4ieQx2Ls8v2rLaJVAYtmDtS_L1U,5406
+chrome_agent/cli.py,sha256=liBXlHN__j8JlqEU3bl8oyOTJHYAPupyWa_pv_KXfas,9423
+chrome_agent/commands.py,sha256=oDAV6BP2XghLYCamPkFXfWHnGAGN6b8WF1mjWU-eqsE,12534
+chrome_agent/connection.py,sha256=idzIkcWvMnDBGwchMO2Q8jfzza74y54FiUC2Fwxhnsw,3220
+chrome_agent/errors.py,sha256=mcC64IOsndqHQNQiDvwDaDqrVzKb_nWIW-oA9R8isGk,1280
+chrome_agent-0.1.0.dist-info/WHEEL,sha256=s_zqWxHFEH8b58BCtf46hFCqPaISurdB9R1XJ8za6XI,80
+chrome_agent-0.1.0.dist-info/entry_points.txt,sha256=ZagAP1naQ_eiXWT4YQ0jCZx0b0ExQju_ivHmDWFTqCs,56
+chrome_agent-0.1.0.dist-info/METADATA,sha256=WbqIpJLNx3dNXaPX_fEZCycZKKlZyJUl3pAEWzWt7DE,7024
+chrome_agent-0.1.0.dist-info/RECORD,,

chrome_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.6
+Root-Is-Purelib: true
+Tag: py3-none-any

chrome_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+chrome-agent = chrome_agent.cli:main
+