Browser Automation

bash quickstart.sh

# When prompted:
# "Enable browser automation? [Y/n]"
# Press Y to enable

import asyncio
from gcu.browser.session import BrowserSession

async def main():
    # Create session
    session = BrowserSession(profile="default")

    # Start browser (persistent mode)
    result = await session.start(
        headless=False,  # Show browser UI
        persistent=True  # Save cookies/storage
    )

    print(f"Browser started: {result['status']}")
    print(f"CDP port: {result['cdp_port']}")
    print(f"Data dir: {result['user_data_dir']}")

asyncio.run(main())

await session.stop()

# Open URL in new tab
result = await session.open_tab(
    url="https://example.com",
    background=False,  # Focus this tab
    wait_until="load"  # Wait for page load
)

print(f"Tab ID: {result['targetId']}")
print(f"Title: {result['title']}")

# Open tab without stealing focus
await session.open_tab(
    url="https://example.com",
    background=True  # Stay on current tab
)

# Close specific tab
await session.close_tab(target_id="tab_123")

# Close current tab
await session.close_tab()

# Switch to tab and bring to front
await session.focus_tab(target_id="tab_123")

tabs = await session.list_tabs()
for tab in tabs:
    print(f"{tab['targetId']}: {tab['title']} ({tab['url']})")
    print(f"  Active: {tab['active']}")

page = session.get_active_page()
await page.goto(
    "https://example.com",
    wait_until="load",
    timeout=60000  # 60 seconds
)

await page.reload()

await page.go_back()
await page.go_forward()

url = page.url
print(f"Current URL: {url}")

# Click by selector
await page.click("button.submit")

# Click with options
await page.click(
    "a.link",
    modifiers=["Control"],  # Ctrl+click
    button="right"  # Right click
)

# Fill input field
await page.fill("input[name='email']", "[email protected]")

# Type with delay (simulate human)
await page.type("input[name='search']", "quantum computing", delay=100)

# Select dropdown
await page.select_option("select[name='country']", "US")

# Check checkbox
await page.check("input[type='checkbox']")

# Uncheck
await page.uncheck("input[type='checkbox']")

# Get text content
text = await page.text_content(".article-body")

# Get inner HTML
html = await page.inner_html(".content")

# Get attribute
href = await page.get_attribute("a.link", "href")

# Get all matching elements
links = await page.query_selector_all("a")
for link in links:
    text = await link.text_content()
    href = await link.get_attribute("href")
    print(f"{text}: {href}")

# Full page screenshot
await page.screenshot(path="page.png", full_page=True)

# Element screenshot
element = await page.query_selector(".content")
await element.screenshot(path="element.png")

# Screenshot as bytes
screenshot_bytes = await page.screenshot()

# Evaluate expression
title = await page.evaluate("document.title")

# Execute function
result = await page.evaluate("""
    () => {
        return document.querySelectorAll('a').length;
    }
""")

# Pass arguments
result = await page.evaluate("""
    (selector) => {
        return document.querySelector(selector).textContent;
    }
""", ".heading")

# Get console messages for current tab
target_id = session.active_page_id
messages = session.console_messages.get(target_id, [])

for msg in messages:
    print(f"{msg['type']}: {msg['text']}")

session = BrowserSession(profile="work")
await session.start(persistent=True)

# Login to website
page = session.get_active_page()
await page.goto("https://app.example.com/login")
await page.fill("input[name='email']", "[email protected]")
await page.fill("input[name='password']", "secret123")
await page.click("button[type='submit']")

# Stop (saves cookies/storage)
await session.stop()

# Restart later - still logged in!
await session.start(persistent=True)
await page.goto("https://app.example.com/dashboard")
# Already authenticated!

~/.hive/agents/{agent-name}/browser/
├── default/              # Default profile
│   ├── Cookies           # Cookies database
│   ├── Local Storage/    # localStorage
│   └── Session Storage/  # sessionStorage
└── work/                 # Work profile
    ├── Cookies
    └── ...

# Start main profile and login
main_session = BrowserSession(profile="authenticated")
await main_session.start(persistent=True)
# ... perform login ...

# Spawn agent sessions with shared auth state
agent1 = await BrowserSession.create_agent_session(
    agent_id="agent-1",
    source_session=main_session
)

agent2 = await BrowserSession.create_agent_session(
    agent_id="agent-2",
    source_session=main_session
)

# Each agent has isolated context but shares cookies
# Changes in agent1 don't affect agent2

# Injected automatically
BROWSER_USER_AGENT = (
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
    "AppleWebKit/537.36 (KHTML, like Gecko) "
    "Chrome/131.0.0.0 Safari/537.36"
)

<!DOCTYPE html>
<html>
  <body>
    <div class="logo">🐝</div>
    <h1>Hive Browser</h1>
    <p>Ready for automation</p>
  </body>
</html>

result = await session.start(persistent=True)
cdp_port = result['cdp_port']

print(f"Connect debugger to: localhost:{cdp_port}")

from playwright.async_api import TimeoutError, Error

try:
    await page.goto(url, timeout=30000)
except TimeoutError:
    print("Page load timeout")
except Error as e:
    print(f"Browser error: {e}")

import asyncio
from gcu.browser.session import BrowserSession

async def scrape_with_auth():
    # Create persistent session
    session = BrowserSession(profile="scraper")
    
    try:
        await session.start(
            headless=False,
            persistent=True
        )
        
        page = session.get_active_page()
        
        # Login (only needed once, then persisted)
        await page.goto("https://example.com/login")
        await page.fill("input[name='email']", "[email protected]")
        await page.fill("input[name='password']", "secret123")
        await page.click("button[type='submit']")
        await page.wait_for_selector(".dashboard")
        
        # Navigate to protected page
        await page.goto("https://example.com/data")
        
        # Extract data
        rows = await page.query_selector_all("table.data tr")
        data = []
        for row in rows:
            cells = await row.query_selector_all("td")
            if cells:
                values = [await cell.text_content() for cell in cells]
                data.append(values)
        
        print(f"Extracted {len(data)} rows")
        return data
        
    finally:
        await session.stop()

if __name__ == "__main__":
    data = asyncio.run(scrape_with_auth())
    print(data)

from framework.runner.runner import AgentRunner

runner = AgentRunner.load("exports/my-agent")

# Register GCU MCP server
runner.register_mcp_server(
    name="browser",
    transport="stdio",
    command="python",
    args=["-m", "gcu.server", "--stdio"]
)

# Use browser tools in agent
result = await runner.run({
    "instruction": "Navigate to example.com and extract the title"
})