LLM-native browser automation engine — Intent DSL → Chrome headless execution. Replace Playwright / Selenium / Puppeteer with an LLM-friendly JSON interface.

80% less token cost than Playwright MCP, same flexibility.

Use cases: LLM agents, browser automation, UI testing, web scraping, form filling, screenshot pipelines, AI-driven test recovery.

pip install guided-browser-runner

from guided_runner import GuidedRunner

runner = GuidedRunner()
result = runner.run({
    "steps": [
        {"action": "goto", "url": "https://example.com/login"},
        {"action": "fill", "selector": "#email", "value": "user@example.com"},
        {"action": "click", "selector": "#login-btn"},
        {"action": "wait", "timeout_ms": 2000},
        {"action": "expect_text", "selector": ".dashboard", "text": "Welcome"},
        # Complex action — LLM generates custom JS
        {"action": "custom", "code": """
            const fileInput = document.querySelector('#upload');
            const dt = new DataTransfer();
            dt.items.add(new File(['hello'], 'test.txt'));
            fileInput.files = dt.files;
            fileInput.dispatchEvent(new Event('change'));
        """},
        {"action": "screenshot"},
    ]
})
print(result["summary"])  # "7/7 steps in 3.2s (0 rewrites)"

{
  "steps": [
    {"action": "click", "selector": "#login-btn"},
    {"action": "fill", "selector": "input[name=email]", "value": "admin"},
    {"action": "custom", "code": "/* LLM-generated JS for drag-and-drop */"}
  ]
}

LLM generates a lightweight JSON plan (~150 tokens) instead of raw code. The Runner executes it — no per-step LLM calls during normal operation.

Template actions execute with zero additional LLM tokens.

{"action": "custom", "code": "/* any JavaScript */"}

Use for: drag-and-drop, file uploads, iframe switching, network intercept, multi-tab, canvas/SVG interaction, shadow DOM — anything the 6 templates don't cover.

The LLM generates the JS directly in the IntentStep, giving you full Playwright-level flexibility at ~50 tokens per custom step.

L1 (auto):   3× retry with exponential backoff — no LLM cost
L2 (LLM):    Diagnose failure → fix selector / skip step / rollback
L3 (fatal):  Fallback to checkpoint screenshot + LLM recovery

On failure the LLM receives the error, step context, and recent attempts, then returns a structured fix decision:

{
  "diagnose": "login button selector changed to .login-v2-btn",
  "type": "fix_selector",
  "new_step": {"action": "click", "selector": ".login-v2-btn"}
}

Guided Runner complements these tools rather than replacing them. Use Playwright for deterministic CI test suites; use Guided Runner for LLM-driven agentic workflows where the steps are dynamic.

• Python 3.10+
• Chrome / Chromium (headless mode)

  # Install Chrome for testing (recommended)
  npx playwright install chrome
  
  # Or use system Chrome
  export GUIDED_CHROME_PATH=/usr/bin/google-chrome

pip install guided-browser-runner
# Or from source
git clone https://github.com/lpc0387/guided-browser-runner.git
cd guided-browser-runner
pip install -e .

• Template actions are statically generated — no exec/eval/fetch
• Custom code has a hard cap of 5 LLM rewrites per run
• All Chrome instances run with --no-sandbox --disable-gpu (isolated mode)

MIT — free for personal and commercial use.

Keywords: browser automation, LLM agent, intent DSL, Chrome headless, AI automation, web scraping, UI testing, Playwright alternative, Puppeteer alternative, Selenium alternative, AI test recovery, LLM-native automation, browser control, headless browser, Python automation