{"id":32532574,"url":"https://github.com/browserbase/agent-browse","last_synced_at":"2025-10-28T12:53:27.315Z","repository":{"id":319335607,"uuid":"1074669117","full_name":"browserbase/agent-browse","owner":"browserbase","description":"Claude Agent SDK with a web browsing tool","archived":false,"fork":false,"pushed_at":"2025-10-17T17:19:59.000Z","size":75,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-18T19:50:41.639Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browserbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-12T08:44:05.000Z","updated_at":"2025-10-17T17:20:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"7d874431-7246-47d1-af3f-bc093d83b153","html_url":"https://github.com/browserbase/agent-browse","commit_stats":null,"previous_names":["browserbase/agent-browse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/browserbase/agent-browse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fagent-browse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fagent-browse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fagent-browse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fagent-browse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browserbase","download_url":"https://codeload.github.com/browserbase/agent-browse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fagent-browse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281441023,"owners_count":26501758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-28T12:53:24.640Z","updated_at":"2025-10-28T12:53:27.301Z","avatar_url":"https://github.com/browserbase.png","language":"TypeScript","readme":"# Claude Agent SDK + Stagehand: Agentic Browser Automation\n\nA demo showing how the **[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview)** (reasoning) combines with **[Stagehand](https://github.com/browserbase/stagehand)** (AI browser automation framework) to create powerful agentic browser automation. Because Stagehand accepts natural language instructions, it's significantly more context-efficient than native Playwright.\n\n## Architecture: Reasoning + Tools\n\nThis demo illustrates a clean separation of concerns:\n\n- **Claude Agent SDK**: Handles all reasoning, planning, and decision-making\n- **Stagehand**: Executes browser actions via natural language commands\n- **Result**: Context-efficient automation where Claude decides *what* to do and Stagehand handles *how* to do it\n\n### Context Efficiency\n\n**Stagehand saves thousands of tokens per interaction** by handling DOM traversal and selector logic internally.\n\n```typescript\n// Traditional: ~500 tokens of context + implementation\n- Full DOM structure passed to Claude\n- Claude generates: await page.click('button[data-testid=\"auth-submit\"][aria-label=\"Submit\"]');\n- Breaks if UI changes\n\n// Stagehand: ~50 tokens\n- Claude calls: act({ action: \"click the submit button\" })\n- Stagehand figures out the selector\n- Resilient to UI changes\n```\n\n## Installation\n\n```bash\nnpm install\n```\n\n**Requirements**: Chrome must be installed on your system.\n\n## Setup\n\nSet your Anthropic API key:\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key\"\n```\n\n**Note**: On first run, the demo will automatically copy your Chrome user data directory to `.chrome-profile` for browser automation. This preserves your cookies and logged-in sessions.\n\n## Usage\n\n### Interactive Mode\n```bash\nnpx tsx agent-browse.ts\n```\n\n### With Initial Prompt\n```bash\nnpx tsx agent-browse.ts \"Go to Hacker News and get the title of the top post\"\n```\n\nAfter Claude responds, you can:\n- Ask follow-up questions\n- Give new instructions\n- Type `exit` or `quit` to end\n\n### Example Tasks\n\n```bash\n# Complex multi-step workflow\nnpx tsx agent-browse.ts \"Go to Hacker News, find the top post, click it, and summarize what it's about\"\n\n# Data extraction with reasoning\nnpx tsx agent-browse.ts \"Navigate to example.com and extract any contact information you can find\"\n\n# Adaptive navigation\nnpx tsx agent-browse.ts \"Go to github.com/browserbase/stagehand, take a screenshot, then find and click the documentation link\"\n```\n\nClaude will:\n1. **Plan** the steps needed (reasoning via Agent SDK)\n2. **Execute** each step using Stagehand tools (natural language browser actions)\n3. **Adapt** based on what it sees (screenshots, extracted data)\n4. **Report** back with results\n\n## Stagehand Tools\n\nThe demo exposes 6 Stagehand browser automation tools via MCP:\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `navigate` | Go to a URL | `navigate({ url: \"https://example.com\" })` |\n| `act` | Perform actions via natural language | `act({ action: \"click the login button\" })` |\n| `extract` | Get structured data from the page | `extract({ instruction: \"extract the title\", schema: { title: \"string\" } })` |\n| `observe` | Discover what's on the page | `observe({ query: \"find all buttons\" })` |\n| `screenshot` | Capture the current page | `screenshot({})` |\n| `close_browser` | Clean up when done | `close_browser({})` |\n\n### How It Works\n\n```typescript\nconst q = query({\n  prompt: generateMessages(),\n  options: {\n    mcpServers: {\n      \"stagehand\": stagehandServer  // Register Stagehand tools\n    },\n    allowedTools: [\n      \"mcp__stagehand__navigate\",\n      \"mcp__stagehand__act\",\n      \"mcp__stagehand__extract\",\n      \"mcp__stagehand__observe\",\n      \"mcp__stagehand__screenshot\",\n      \"mcp__stagehand__close_browser\"\n    ]\n  }\n});\n```\n\n**The flow:**\n1. Claude (via Agent SDK) decides what browser action to take\n2. Claude calls a Stagehand MCP tool with natural language parameters\n3. Stagehand translates the natural language into precise browser actions\n4. Results flow back to Claude for the next decision\n\n## Troubleshooting\n\n### Chrome not found\n\nInstall Chrome for your platform:\n- **macOS**: https://www.google.com/chrome/\n- **Windows**: https://www.google.com/chrome/\n- **Linux**: `sudo apt install google-chrome-stable`\n\n### Profile refresh\n\nTo refresh cookies from your main Chrome profile:\n```bash\nrm -rf .chrome-profile\n```\n\n## Resources\n\n- [Claude Agent SDK Documentation](https://docs.claude.com/en/api/agent-sdk/overview)\n- [Stagehand Documentation](https://github.com/browserbase/stagehand)\n- [MCP (Model Context Protocol)](https://modelcontextprotocol.io)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fagent-browse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowserbase%2Fagent-browse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fagent-browse/lists"}