docs
This commit is contained in:
Chris Tate
@@ -42,3 +42,9 @@ yarn.lock
|
||||
|
||||
# opensrc - source code for packages
|
||||
opensrc/
|
||||
|
||||
# Docs site
|
||||
docs/node_modules/
|
||||
docs/.next/
|
||||
docs/out/
|
||||
docs/package-lock.json
|
||||
|
||||
@@ -0,0 +1,322 @@
|
||||
#!/usr/bin/env npx tsx
|
||||
/**
|
||||
* Comprehensive Benchmark: agent-browser vs playwright-mcp
|
||||
*
|
||||
* Tests realistic AI agent workflows on real websites.
|
||||
*/
|
||||
|
||||
import { execSync, spawn } from 'child_process';
|
||||
import * as path from 'path';
|
||||
|
||||
interface Result {
|
||||
tool: string;
|
||||
workflow: string;
|
||||
operation: string;
|
||||
timeMs: number;
|
||||
outputBytes: number;
|
||||
}
|
||||
|
||||
const results: Result[] = [];
|
||||
|
||||
function formatTime(ms: number): string {
|
||||
if (ms < 1000) return `${ms.toFixed(0)}ms`;
|
||||
return `${(ms / 1000).toFixed(2)}s`;
|
||||
}
|
||||
|
||||
function formatBytes(bytes: number): string {
|
||||
if (bytes < 1024) return `${bytes}B`;
|
||||
return `${(bytes / 1024).toFixed(1)}KB`;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Agent-Browser Runner
|
||||
// ============================================================================
|
||||
|
||||
function runAB(args: string[], session: string = 'bench'): { ms: number; output: string } {
|
||||
const start = performance.now();
|
||||
let output = '';
|
||||
try {
|
||||
output = execSync(`./bin/agent-browser ${args.join(' ')}`, {
|
||||
stdio: 'pipe',
|
||||
timeout: 30000,
|
||||
env: { ...process.env, AGENT_BROWSER_SESSION: session },
|
||||
}).toString();
|
||||
} catch (e: any) {
|
||||
output = e.stdout?.toString() || e.message || '';
|
||||
}
|
||||
return { ms: performance.now() - start, output };
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Playwright-MCP Runner
|
||||
// ============================================================================
|
||||
|
||||
interface MCPClient {
|
||||
call: (tool: string, args: Record<string, unknown>) => Promise<{ ms: number; output: string }>;
|
||||
close: () => void;
|
||||
}
|
||||
|
||||
async function createMCPClient(): Promise<MCPClient> {
|
||||
const mcpPath = path.join(process.cwd(), 'opensrc/repos/github.com/microsoft/playwright-mcp/cli.js');
|
||||
const proc = spawn('node', [mcpPath, '--headless'], { stdio: ['pipe', 'pipe', 'pipe'] });
|
||||
|
||||
let buffer = '';
|
||||
let requestId = 0;
|
||||
const pending = new Map<number, { resolve: (v: any) => void; reject: (e: Error) => void }>();
|
||||
|
||||
proc.stdout!.on('data', (data: Buffer) => {
|
||||
buffer += data.toString();
|
||||
const lines = buffer.split('\n');
|
||||
buffer = lines.pop() || '';
|
||||
for (const line of lines) {
|
||||
if (!line.trim()) continue;
|
||||
try {
|
||||
const msg = JSON.parse(line);
|
||||
if (msg.id !== undefined && pending.has(msg.id)) {
|
||||
pending.get(msg.id)!.resolve(msg);
|
||||
pending.delete(msg.id);
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
});
|
||||
|
||||
const send = (method: string, params: Record<string, unknown>): Promise<any> => {
|
||||
const id = ++requestId;
|
||||
return new Promise((resolve, reject) => {
|
||||
pending.set(id, { resolve, reject });
|
||||
proc.stdin!.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
|
||||
setTimeout(() => {
|
||||
if (pending.has(id)) {
|
||||
pending.delete(id);
|
||||
reject(new Error('Timeout'));
|
||||
}
|
||||
}, 30000);
|
||||
});
|
||||
};
|
||||
|
||||
// Initialize
|
||||
await send('initialize', {
|
||||
protocolVersion: '2024-11-05',
|
||||
capabilities: {},
|
||||
clientInfo: { name: 'benchmark', version: '1.0.0' },
|
||||
});
|
||||
proc.stdin!.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }) + '\n');
|
||||
|
||||
return {
|
||||
call: async (tool: string, args: Record<string, unknown>) => {
|
||||
const start = performance.now();
|
||||
const result = await send('tools/call', { name: tool, arguments: args });
|
||||
return { ms: performance.now() - start, output: JSON.stringify(result) };
|
||||
},
|
||||
close: () => proc.kill(),
|
||||
};
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Workflows
|
||||
// ============================================================================
|
||||
|
||||
interface Workflow {
|
||||
name: string;
|
||||
description: string;
|
||||
steps: Array<{
|
||||
name: string;
|
||||
ab: string[];
|
||||
mcp: { tool: string; args: Record<string, unknown> };
|
||||
}>;
|
||||
}
|
||||
|
||||
const workflows: Workflow[] = [
|
||||
{
|
||||
name: 'Wikipedia Research',
|
||||
description: 'Navigate Wikipedia, read content, follow links',
|
||||
steps: [
|
||||
{ name: 'Navigate', ab: ['open', 'https://en.wikipedia.org/wiki/Artificial_intelligence'], mcp: { tool: 'browser_navigate', args: { url: 'https://en.wikipedia.org/wiki/Artificial_intelligence' } } },
|
||||
{ name: 'Snapshot', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Get title', ab: ['get', 'title'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Snapshot 2', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Click link', ab: ['click', 'a[href="/wiki/Machine_learning"]'], mcp: { tool: 'browser_click', args: { element: 'Machine learning', ref: 'internal link' } } },
|
||||
{ name: 'Snapshot 3', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
],
|
||||
},
|
||||
{
|
||||
name: 'GitHub Browse',
|
||||
description: 'Browse a GitHub repository',
|
||||
steps: [
|
||||
{ name: 'Navigate', ab: ['open', 'https://github.com/anthropics/anthropic-cookbook'], mcp: { tool: 'browser_navigate', args: { url: 'https://github.com/anthropics/anthropic-cookbook' } } },
|
||||
{ name: 'Snapshot', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Get URL', ab: ['get', 'url'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Eval (stars)', ab: ['eval', 'document.querySelector("#repo-stars-counter-star")?.textContent'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Snapshot 2', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
],
|
||||
},
|
||||
{
|
||||
name: 'Hacker News',
|
||||
description: 'Browse Hacker News front page',
|
||||
steps: [
|
||||
{ name: 'Navigate', ab: ['open', 'https://news.ycombinator.com'], mcp: { tool: 'browser_navigate', args: { url: 'https://news.ycombinator.com' } } },
|
||||
{ name: 'Snapshot', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Eval (count)', ab: ['eval', 'document.querySelectorAll(".athing").length'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Snapshot 2', ab: ['snapshot', '-i'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
{ name: 'Get title', ab: ['get', 'title'], mcp: { tool: 'browser_snapshot', args: {} } },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
// ============================================================================
|
||||
// Run Benchmarks
|
||||
// ============================================================================
|
||||
|
||||
async function runAgentBrowser(workflow: Workflow, session: string): Promise<void> {
|
||||
// Cleanup
|
||||
try { runAB(['close'], session); } catch {}
|
||||
await sleep(100);
|
||||
|
||||
for (const step of workflow.steps) {
|
||||
const r = runAB(step.ab, session);
|
||||
results.push({
|
||||
tool: 'agent-browser',
|
||||
workflow: workflow.name,
|
||||
operation: step.name,
|
||||
timeMs: r.ms,
|
||||
outputBytes: r.output.length,
|
||||
});
|
||||
}
|
||||
|
||||
try { runAB(['close'], session); } catch {}
|
||||
}
|
||||
|
||||
async function runPlaywrightMCP(workflow: Workflow): Promise<void> {
|
||||
let client: MCPClient | null = null;
|
||||
try {
|
||||
client = await createMCPClient();
|
||||
|
||||
for (const step of workflow.steps) {
|
||||
const r = await client.call(step.mcp.tool, step.mcp.args);
|
||||
results.push({
|
||||
tool: 'playwright-mcp',
|
||||
workflow: workflow.name,
|
||||
operation: step.name,
|
||||
timeMs: r.ms,
|
||||
outputBytes: r.output.length,
|
||||
});
|
||||
}
|
||||
|
||||
await client.call('browser_close', {});
|
||||
} catch (e) {
|
||||
console.log(` ⚠ MCP error: ${e}`);
|
||||
} finally {
|
||||
client?.close();
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Reporting
|
||||
// ============================================================================
|
||||
|
||||
function printResults(): void {
|
||||
console.log('\n' + '═'.repeat(80));
|
||||
console.log('📊 DETAILED RESULTS');
|
||||
console.log('═'.repeat(80));
|
||||
|
||||
for (const workflow of workflows) {
|
||||
console.log(`\n📋 ${workflow.name}`);
|
||||
console.log('─'.repeat(70));
|
||||
console.log('│ Operation │ agent-browser │ playwright-mcp │ Diff │');
|
||||
console.log('├────────────────────┼───────────────┼────────────────┼───────────┤');
|
||||
|
||||
let abTotal = 0, mcpTotal = 0;
|
||||
|
||||
for (const step of workflow.steps) {
|
||||
const ab = results.find(r => r.tool === 'agent-browser' && r.workflow === workflow.name && r.operation === step.name);
|
||||
const mcp = results.find(r => r.tool === 'playwright-mcp' && r.workflow === workflow.name && r.operation === step.name);
|
||||
|
||||
const abTime = ab?.timeMs || 0;
|
||||
const mcpTime = mcp?.timeMs || 0;
|
||||
abTotal += abTime;
|
||||
mcpTotal += mcpTime;
|
||||
|
||||
const diff = mcpTime - abTime;
|
||||
const diffStr = diff > 0 ? `+${formatTime(diff)}` : formatTime(diff);
|
||||
|
||||
console.log(`│ ${step.name.padEnd(18)} │ ${formatTime(abTime).padEnd(13)} │ ${formatTime(mcpTime).padEnd(14)} │ ${diffStr.padEnd(9)} │`);
|
||||
}
|
||||
|
||||
console.log('├────────────────────┼───────────────┼────────────────┼───────────┤');
|
||||
const totalDiff = mcpTotal - abTotal;
|
||||
const totalDiffStr = totalDiff > 0 ? `+${formatTime(totalDiff)}` : formatTime(totalDiff);
|
||||
console.log(`│ ${'TOTAL'.padEnd(18)} │ ${formatTime(abTotal).padEnd(13)} │ ${formatTime(mcpTotal).padEnd(14)} │ ${totalDiffStr.padEnd(9)} │`);
|
||||
console.log('└────────────────────┴───────────────┴────────────────┴───────────┘');
|
||||
}
|
||||
|
||||
// Summary
|
||||
const abTotalAll = results.filter(r => r.tool === 'agent-browser').reduce((s, r) => s + r.timeMs, 0);
|
||||
const mcpTotalAll = results.filter(r => r.tool === 'playwright-mcp').reduce((s, r) => s + r.timeMs, 0);
|
||||
const abOps = results.filter(r => r.tool === 'agent-browser').length;
|
||||
const mcpOps = results.filter(r => r.tool === 'playwright-mcp').length;
|
||||
|
||||
console.log('\n' + '═'.repeat(80));
|
||||
console.log('📈 SUMMARY');
|
||||
console.log('═'.repeat(80));
|
||||
console.log(`\n Workflows tested: ${workflows.length}`);
|
||||
console.log(` Total operations: ${abOps} (agent-browser), ${mcpOps} (playwright-mcp)`);
|
||||
console.log(`\n agent-browser total: ${formatTime(abTotalAll)} (${(abTotalAll / abOps).toFixed(0)}ms avg/op)`);
|
||||
console.log(` playwright-mcp total: ${formatTime(mcpTotalAll)} (${(mcpTotalAll / mcpOps).toFixed(0)}ms avg/op)`);
|
||||
|
||||
if (abTotalAll < mcpTotalAll) {
|
||||
console.log(`\n ✅ agent-browser is ${((mcpTotalAll - abTotalAll) / 1000).toFixed(2)}s faster overall`);
|
||||
} else {
|
||||
console.log(`\n ⏱️ playwright-mcp is ${((abTotalAll - mcpTotalAll) / 1000).toFixed(2)}s faster overall`);
|
||||
}
|
||||
|
||||
// Context usage
|
||||
const abBytes = results.filter(r => r.tool === 'agent-browser').reduce((s, r) => s + r.outputBytes, 0);
|
||||
const mcpBytes = results.filter(r => r.tool === 'playwright-mcp').reduce((s, r) => s + r.outputBytes, 0);
|
||||
|
||||
console.log(`\n Context usage:`);
|
||||
console.log(` agent-browser: ${formatBytes(abBytes)} (~${Math.ceil(abBytes / 4)} tokens)`);
|
||||
console.log(` playwright-mcp: ${formatBytes(mcpBytes)} (~${Math.ceil(mcpBytes / 4)} tokens)`);
|
||||
|
||||
console.log('\n' + '═'.repeat(80));
|
||||
}
|
||||
|
||||
function sleep(ms: number): Promise<void> {
|
||||
return new Promise(r => setTimeout(r, ms));
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Main
|
||||
// ============================================================================
|
||||
|
||||
async function main(): Promise<void> {
|
||||
console.log('═'.repeat(80));
|
||||
console.log('🚀 COMPREHENSIVE BENCHMARK: agent-browser vs playwright-mcp');
|
||||
console.log('═'.repeat(80));
|
||||
console.log('\nWorkflows:');
|
||||
for (const w of workflows) {
|
||||
console.log(` • ${w.name}: ${w.description} (${w.steps.length} steps)`);
|
||||
}
|
||||
|
||||
console.log('\n🔨 Building...');
|
||||
execSync('pnpm build', { cwd: process.cwd(), stdio: 'inherit' });
|
||||
|
||||
for (const workflow of workflows) {
|
||||
console.log(`\n${'─'.repeat(80)}`);
|
||||
console.log(`📋 Running: ${workflow.name}`);
|
||||
console.log('─'.repeat(80));
|
||||
|
||||
console.log('\n agent-browser:');
|
||||
await runAgentBrowser(workflow, `ab-${workflow.name.toLowerCase().replace(/\s+/g, '-')}`);
|
||||
const abTime = results.filter(r => r.tool === 'agent-browser' && r.workflow === workflow.name).reduce((s, r) => s + r.timeMs, 0);
|
||||
console.log(` ✓ Completed in ${formatTime(abTime)}`);
|
||||
|
||||
console.log('\n playwright-mcp:');
|
||||
await runPlaywrightMCP(workflow);
|
||||
const mcpTime = results.filter(r => r.tool === 'playwright-mcp' && r.workflow === workflow.name).reduce((s, r) => s + r.timeMs, 0);
|
||||
console.log(` ✓ Completed in ${formatTime(mcpTime)}`);
|
||||
}
|
||||
|
||||
printResults();
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
@@ -0,0 +1,41 @@
|
||||
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
|
||||
|
||||
# dependencies
|
||||
/node_modules
|
||||
/.pnp
|
||||
.pnp.*
|
||||
.yarn/*
|
||||
!.yarn/patches
|
||||
!.yarn/plugins
|
||||
!.yarn/releases
|
||||
!.yarn/versions
|
||||
|
||||
# testing
|
||||
/coverage
|
||||
|
||||
# next.js
|
||||
/.next/
|
||||
/out/
|
||||
|
||||
# production
|
||||
/build
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# env files (can opt-in for committing if needed)
|
||||
.env*
|
||||
|
||||
# vercel
|
||||
.vercel
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
@@ -0,0 +1,18 @@
|
||||
import { defineConfig, globalIgnores } from "eslint/config";
|
||||
import nextVitals from "eslint-config-next/core-web-vitals";
|
||||
import nextTs from "eslint-config-next/typescript";
|
||||
|
||||
const eslintConfig = defineConfig([
|
||||
...nextVitals,
|
||||
...nextTs,
|
||||
// Override default ignores of eslint-config-next.
|
||||
globalIgnores([
|
||||
// Default ignores of eslint-config-next:
|
||||
".next/**",
|
||||
"out/**",
|
||||
"build/**",
|
||||
"next-env.d.ts",
|
||||
]),
|
||||
]);
|
||||
|
||||
export default eslintConfig;
|
||||
@@ -0,0 +1,7 @@
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
/* config options here */
|
||||
};
|
||||
|
||||
export default nextConfig;
|
||||
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"name": "docs",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"lint": "eslint"
|
||||
},
|
||||
"dependencies": {
|
||||
"next": "16.1.1",
|
||||
"react": "19.2.3",
|
||||
"react-dom": "19.2.3",
|
||||
"shiki": "^3.21.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/postcss": "^4",
|
||||
"@types/node": "^20",
|
||||
"@types/react": "^19",
|
||||
"@types/react-dom": "^19",
|
||||
"eslint": "^9",
|
||||
"eslint-config-next": "16.1.1",
|
||||
"tailwindcss": "^4",
|
||||
"typescript": "^5"
|
||||
}
|
||||
}
|
||||
Generated
+4327
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,7 @@
|
||||
const config = {
|
||||
plugins: {
|
||||
"@tailwindcss/postcss": {},
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
@@ -0,0 +1,72 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function AgentMode() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Agent Mode</h1>
|
||||
<p>
|
||||
agent-browser works with any AI coding agent. Use <code>--json</code> for machine-readable output.
|
||||
</p>
|
||||
|
||||
<h2>Compatible agents</h2>
|
||||
<ul>
|
||||
<li>Claude Code</li>
|
||||
<li>Cursor</li>
|
||||
<li>GitHub Copilot</li>
|
||||
<li>OpenAI Codex</li>
|
||||
<li>Google Gemini</li>
|
||||
<li>opencode</li>
|
||||
<li>Any agent that can run shell commands</li>
|
||||
</ul>
|
||||
|
||||
<h2>JSON output</h2>
|
||||
<CodeBlock code={`agent-browser snapshot --json
|
||||
# {"success":true,"data":{"snapshot":"...","refs":{...}}}
|
||||
|
||||
agent-browser get text @e1 --json
|
||||
agent-browser is visible @e2 --json`} />
|
||||
|
||||
<h2>Optimal workflow</h2>
|
||||
<CodeBlock code={`# 1. Navigate and get snapshot
|
||||
agent-browser open example.com
|
||||
agent-browser snapshot -i --json # AI parses tree and refs
|
||||
|
||||
# 2. AI identifies target refs from snapshot
|
||||
# 3. Execute actions using refs
|
||||
agent-browser click @e2
|
||||
agent-browser fill @e3 "input text"
|
||||
|
||||
# 4. Get new snapshot if page changed
|
||||
agent-browser snapshot -i --json`} />
|
||||
|
||||
<h2>Integration</h2>
|
||||
|
||||
<h3>Just ask</h3>
|
||||
<p>The simplest approach:</p>
|
||||
<CodeBlock lang="text" code="Use agent-browser to test the login flow. Run agent-browser --help to see available commands." />
|
||||
<p>The <code>--help</code> output is comprehensive.</p>
|
||||
|
||||
<h3>AGENTS.md / CLAUDE.md</h3>
|
||||
<p>For consistent results, add to your instructions file:</p>
|
||||
<CodeBlock lang="markdown" code={`## Browser Automation
|
||||
|
||||
Use \`agent-browser\` for web automation. Run \`agent-browser --help\` for all commands.
|
||||
|
||||
Core workflow:
|
||||
1. \`agent-browser open <url>\` - Navigate to page
|
||||
2. \`agent-browser snapshot -i\` - Get interactive elements with refs (@e1, @e2)
|
||||
3. \`agent-browser click @e1\` / \`fill @e2 "text"\` - Interact using refs
|
||||
4. Re-snapshot after page changes`} />
|
||||
|
||||
<h3>Claude Code skill</h3>
|
||||
<p>For richer context:</p>
|
||||
<CodeBlock code="cp -r node_modules/agent-browser/skills/agent-browser .claude/skills/" />
|
||||
<p>Or download:</p>
|
||||
<CodeBlock code={`mkdir -p .claude/skills/agent-browser
|
||||
curl -o .claude/skills/agent-browser/SKILL.md \\
|
||||
https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function CDPMode() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>CDP Mode</h1>
|
||||
<p>Connect to an existing browser via Chrome DevTools Protocol:</p>
|
||||
<CodeBlock code={`# Connect to Electron app
|
||||
agent-browser --cdp 9222 snapshot
|
||||
|
||||
# Connect to Chrome with remote debugging
|
||||
# (Start Chrome with: google-chrome --remote-debugging-port=9222)
|
||||
agent-browser --cdp 9222 open about:blank`} />
|
||||
|
||||
<h2>Use cases</h2>
|
||||
<p>This enables control of:</p>
|
||||
<ul>
|
||||
<li>Electron apps</li>
|
||||
<li>Chrome/Chromium with remote debugging</li>
|
||||
<li>WebView2 applications</li>
|
||||
<li>Any browser exposing a CDP endpoint</li>
|
||||
</ul>
|
||||
|
||||
<h2>Global options</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>--session <name></code></td>
|
||||
<td>Use isolated session</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--headers <json></code></td>
|
||||
<td>HTTP headers scoped to origin</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--executable-path</code></td>
|
||||
<td>Custom browser executable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--json</code></td>
|
||||
<td>JSON output for agents</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--full, -f</code></td>
|
||||
<td>Full page screenshot</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--name, -n</code></td>
|
||||
<td>Locator name filter</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--exact</code></td>
|
||||
<td>Exact text match</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--headed</code></td>
|
||||
<td>Show browser window</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--cdp <port></code></td>
|
||||
<td>CDP connection port</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--debug</code></td>
|
||||
<td>Debug output</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,121 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Commands() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Commands</h1>
|
||||
|
||||
<h2>Core</h2>
|
||||
<CodeBlock code={`agent-browser open <url> # Navigate (aliases: goto, navigate)
|
||||
agent-browser click <sel> # Click element
|
||||
agent-browser dblclick <sel> # Double-click
|
||||
agent-browser fill <sel> <text> # Clear and fill
|
||||
agent-browser type <sel> <text> # Type into element
|
||||
agent-browser press <key> # Press key (Enter, Tab, Control+a)
|
||||
agent-browser hover <sel> # Hover element
|
||||
agent-browser select <sel> <val> # Select dropdown option
|
||||
agent-browser check <sel> # Check checkbox
|
||||
agent-browser uncheck <sel> # Uncheck checkbox
|
||||
agent-browser scroll <dir> [px] # Scroll (up/down/left/right)
|
||||
agent-browser screenshot [path] # Screenshot (--full for full page)
|
||||
agent-browser snapshot # Accessibility tree with refs
|
||||
agent-browser eval <js> # Run JavaScript
|
||||
agent-browser close # Close browser`} />
|
||||
|
||||
<h2>Get info</h2>
|
||||
<CodeBlock code={`agent-browser get text <sel> # Get text content
|
||||
agent-browser get html <sel> # Get innerHTML
|
||||
agent-browser get value <sel> # Get input value
|
||||
agent-browser get attr <sel> <attr> # Get attribute
|
||||
agent-browser get title # Get page title
|
||||
agent-browser get url # Get current URL
|
||||
agent-browser get count <sel> # Count matching elements
|
||||
agent-browser get box <sel> # Get bounding box`} />
|
||||
|
||||
<h2>Check state</h2>
|
||||
<CodeBlock code={`agent-browser is visible <sel> # Check if visible
|
||||
agent-browser is enabled <sel> # Check if enabled
|
||||
agent-browser is checked <sel> # Check if checked`} />
|
||||
|
||||
<h2>Find elements</h2>
|
||||
<p>Semantic locators with actions (<code>click</code>, <code>fill</code>, <code>check</code>, <code>hover</code>, <code>text</code>):</p>
|
||||
<CodeBlock code={`agent-browser find role <role> <action> [value]
|
||||
agent-browser find text <text> <action>
|
||||
agent-browser find label <label> <action> [value]
|
||||
agent-browser find placeholder <ph> <action> [value]
|
||||
agent-browser find testid <id> <action> [value]
|
||||
agent-browser find first <sel> <action> [value]
|
||||
agent-browser find nth <n> <sel> <action> [value]`} />
|
||||
<p>Examples:</p>
|
||||
<CodeBlock code={`agent-browser find role button click --name "Submit"
|
||||
agent-browser find label "Email" fill "test@test.com"
|
||||
agent-browser find first ".item" click`} />
|
||||
|
||||
<h2>Wait</h2>
|
||||
<CodeBlock code={`agent-browser wait <selector> # Wait for element
|
||||
agent-browser wait <ms> # Wait for time
|
||||
agent-browser wait --text "Welcome" # Wait for text
|
||||
agent-browser wait --url "**/dash" # Wait for URL pattern
|
||||
agent-browser wait --load networkidle # Wait for load state
|
||||
agent-browser wait --fn "condition" # Wait for JS condition`} />
|
||||
|
||||
<h2>Mouse</h2>
|
||||
<CodeBlock code={`agent-browser mouse move <x> <y> # Move mouse
|
||||
agent-browser mouse down [button] # Press button
|
||||
agent-browser mouse up [button] # Release button
|
||||
agent-browser mouse wheel <dy> [dx] # Scroll wheel`} />
|
||||
|
||||
<h2>Settings</h2>
|
||||
<CodeBlock code={`agent-browser set viewport <w> <h> # Set viewport size
|
||||
agent-browser set device <name> # Emulate device ("iPhone 14")
|
||||
agent-browser set geo <lat> <lng> # Set geolocation
|
||||
agent-browser set offline [on|off] # Toggle offline mode
|
||||
agent-browser set headers <json> # Extra HTTP headers
|
||||
agent-browser set credentials <u> <p> # HTTP basic auth
|
||||
agent-browser set media [dark|light] # Emulate color scheme`} />
|
||||
|
||||
<h2>Cookies & storage</h2>
|
||||
<CodeBlock code={`agent-browser cookies # Get all cookies
|
||||
agent-browser cookies set <name> <val> # Set cookie
|
||||
agent-browser cookies clear # Clear cookies
|
||||
|
||||
agent-browser storage local # Get all localStorage
|
||||
agent-browser storage local <key> # Get specific key
|
||||
agent-browser storage local set <k> <v> # Set value
|
||||
agent-browser storage local clear # Clear all
|
||||
|
||||
agent-browser storage session # Same for sessionStorage`} />
|
||||
|
||||
<h2>Network</h2>
|
||||
<CodeBlock code={`agent-browser network route <url> # Intercept requests
|
||||
agent-browser network route <url> --abort # Block requests
|
||||
agent-browser network route <url> --body <json> # Mock response
|
||||
agent-browser network unroute [url] # Remove routes
|
||||
agent-browser network requests # View tracked requests`} />
|
||||
|
||||
<h2>Tabs & frames</h2>
|
||||
<CodeBlock code={`agent-browser tab # List tabs
|
||||
agent-browser tab new [url] # New tab
|
||||
agent-browser tab <n> # Switch to tab
|
||||
agent-browser tab close [n] # Close tab
|
||||
agent-browser frame <sel> # Switch to iframe
|
||||
agent-browser frame main # Back to main frame`} />
|
||||
|
||||
<h2>Debug</h2>
|
||||
<CodeBlock code={`agent-browser trace start [path] # Start trace
|
||||
agent-browser trace stop [path] # Stop and save trace
|
||||
agent-browser console # View console messages
|
||||
agent-browser errors # View page errors
|
||||
agent-browser highlight <sel> # Highlight element
|
||||
agent-browser state save <path> # Save auth state
|
||||
agent-browser state load <path> # Load auth state`} />
|
||||
|
||||
<h2>Navigation</h2>
|
||||
<CodeBlock code={`agent-browser back # Go back
|
||||
agent-browser forward # Go forward
|
||||
agent-browser reload # Reload page`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
@@ -0,0 +1,182 @@
|
||||
@import "tailwindcss";
|
||||
|
||||
:root {
|
||||
--background: #000000;
|
||||
--foreground: #ededed;
|
||||
--muted: #888888;
|
||||
--border: #222222;
|
||||
--accent: #ededed;
|
||||
}
|
||||
|
||||
@theme inline {
|
||||
--color-background: var(--background);
|
||||
--color-foreground: var(--foreground);
|
||||
--color-muted: var(--muted);
|
||||
--color-border: var(--border);
|
||||
--color-accent: var(--accent);
|
||||
--font-sans: var(--font-geist);
|
||||
--font-mono: var(--font-geist-mono);
|
||||
}
|
||||
|
||||
body {
|
||||
background: var(--background);
|
||||
color: var(--foreground);
|
||||
font-family: var(--font-geist), system-ui, sans-serif;
|
||||
}
|
||||
|
||||
/* Scrollbar */
|
||||
::-webkit-scrollbar {
|
||||
width: 6px;
|
||||
height: 6px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-track {
|
||||
background: transparent;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb {
|
||||
background: #333;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb:hover {
|
||||
background: #444;
|
||||
}
|
||||
|
||||
/* Code blocks */
|
||||
pre {
|
||||
background: #111 !important;
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 4px;
|
||||
padding: 0.875rem;
|
||||
overflow-x: auto;
|
||||
font-family: var(--font-geist-mono), monospace;
|
||||
font-size: 0.8125rem;
|
||||
line-height: 1.7;
|
||||
}
|
||||
|
||||
.code-block pre {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.code-block {
|
||||
margin-bottom: 1.25rem;
|
||||
}
|
||||
|
||||
@media (max-width: 640px) {
|
||||
pre {
|
||||
font-size: 0.75rem;
|
||||
padding: 0.75rem;
|
||||
}
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: var(--font-geist-mono), monospace;
|
||||
}
|
||||
|
||||
:not(pre) > code {
|
||||
background: #1a1a1a;
|
||||
padding: 0.125rem 0.375rem;
|
||||
border-radius: 3px;
|
||||
font-size: 0.875em;
|
||||
}
|
||||
|
||||
/* Prose */
|
||||
.prose {
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
.prose h1 {
|
||||
font-size: 1.5rem;
|
||||
font-weight: 500;
|
||||
letter-spacing: -0.02em;
|
||||
margin-bottom: 0.5rem;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
@media (min-width: 640px) {
|
||||
.prose h1 {
|
||||
font-size: 1.75rem;
|
||||
}
|
||||
}
|
||||
|
||||
.prose h2 {
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
letter-spacing: 0;
|
||||
text-transform: uppercase;
|
||||
color: var(--muted);
|
||||
margin-top: 3rem;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
.prose h3 {
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
margin-top: 2rem;
|
||||
margin-bottom: 0.75rem;
|
||||
color: #ccc;
|
||||
}
|
||||
|
||||
.prose p {
|
||||
margin-bottom: 1.25rem;
|
||||
line-height: 1.7;
|
||||
color: var(--muted);
|
||||
font-size: 0.9375rem;
|
||||
}
|
||||
|
||||
.prose ul, .prose ol {
|
||||
margin-bottom: 1.25rem;
|
||||
padding-left: 1.25rem;
|
||||
}
|
||||
|
||||
.prose li {
|
||||
margin-bottom: 0.5rem;
|
||||
color: var(--muted);
|
||||
font-size: 0.9375rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.prose li strong {
|
||||
color: #ccc;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.prose a {
|
||||
color: var(--foreground);
|
||||
text-decoration: underline;
|
||||
text-underline-offset: 2px;
|
||||
}
|
||||
|
||||
.prose a:hover {
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.prose table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1.5rem 0;
|
||||
font-size: 0.8125rem;
|
||||
}
|
||||
|
||||
.prose th, .prose td {
|
||||
text-align: left;
|
||||
padding: 0.625rem 0.875rem;
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
|
||||
.prose th {
|
||||
font-weight: 500;
|
||||
color: var(--muted);
|
||||
text-transform: uppercase;
|
||||
font-size: 0.75rem;
|
||||
letter-spacing: 0.025em;
|
||||
}
|
||||
|
||||
.prose td {
|
||||
color: var(--muted);
|
||||
}
|
||||
|
||||
.prose td code {
|
||||
color: var(--foreground);
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Installation() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Installation</h1>
|
||||
|
||||
<h2>npm (recommended)</h2>
|
||||
<CodeBlock code={`npm install -g agent-browser
|
||||
agent-browser install # Download Chromium`} />
|
||||
|
||||
<h2>From source</h2>
|
||||
<CodeBlock code={`git clone https://github.com/vercel-labs/agent-browser
|
||||
cd agent-browser
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm build:native
|
||||
./bin/agent-browser install
|
||||
pnpm link --global`} />
|
||||
|
||||
<h2>Linux dependencies</h2>
|
||||
<p>On Linux, install system dependencies:</p>
|
||||
<CodeBlock code={`agent-browser install --with-deps
|
||||
# or manually: npx playwright install-deps chromium`} />
|
||||
|
||||
<h2>Custom browser</h2>
|
||||
<p>
|
||||
Use a custom browser executable instead of bundled Chromium:
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Serverless</strong> - Use <code>@sparticuz/chromium</code> (~50MB vs ~684MB)</li>
|
||||
<li><strong>System browser</strong> - Use existing Chrome installation</li>
|
||||
<li><strong>Custom builds</strong> - Use modified browser builds</li>
|
||||
</ul>
|
||||
|
||||
<CodeBlock code={`# Via flag
|
||||
agent-browser --executable-path /path/to/chromium open example.com
|
||||
|
||||
# Via environment variable
|
||||
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com`} />
|
||||
|
||||
<h3>Serverless example</h3>
|
||||
<CodeBlock lang="typescript" code={`import chromium from '@sparticuz/chromium';
|
||||
import { BrowserManager } from 'agent-browser';
|
||||
|
||||
export async function handler() {
|
||||
const browser = new BrowserManager();
|
||||
await browser.launch({
|
||||
executablePath: await chromium.executablePath(),
|
||||
headless: true,
|
||||
});
|
||||
// ... use browser
|
||||
}`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
import type { Metadata } from "next";
|
||||
import { Geist, Geist_Mono } from "next/font/google";
|
||||
import "./globals.css";
|
||||
import { Sidebar } from "@/components/sidebar";
|
||||
|
||||
const geist = Geist({
|
||||
variable: "--font-geist",
|
||||
subsets: ["latin"],
|
||||
});
|
||||
|
||||
const geistMono = Geist_Mono({
|
||||
variable: "--font-geist-mono",
|
||||
subsets: ["latin"],
|
||||
});
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "agent-browser",
|
||||
description: "Headless browser automation CLI for AI agents",
|
||||
};
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: Readonly<{
|
||||
children: React.ReactNode;
|
||||
}>) {
|
||||
return (
|
||||
<html lang="en" className="dark">
|
||||
<body
|
||||
className={`${geist.variable} ${geistMono.variable} antialiased bg-zinc-950 text-zinc-100`}
|
||||
>
|
||||
<div className="flex min-h-screen">
|
||||
<Sidebar />
|
||||
<main className="flex-1 overflow-auto pt-14 lg:pt-0">
|
||||
{children}
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>agent-browser</h1>
|
||||
<p>
|
||||
Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.
|
||||
</p>
|
||||
|
||||
<CodeBlock code="npm install -g agent-browser" />
|
||||
|
||||
<h2>Features</h2>
|
||||
<ul>
|
||||
<li><strong>Universal</strong> - Works with any AI agent: Claude Code, Cursor, Codex, Copilot, Gemini, opencode, and more</li>
|
||||
<li><strong>AI-first</strong> - Snapshot returns accessibility tree with refs for deterministic element selection</li>
|
||||
<li><strong>Fast</strong> - Native Rust CLI for instant command parsing</li>
|
||||
<li><strong>Complete</strong> - 50+ commands for navigation, forms, screenshots, network, storage</li>
|
||||
<li><strong>Sessions</strong> - Multiple isolated browser instances with separate auth</li>
|
||||
<li><strong>Cross-platform</strong> - macOS, Linux, Windows with native binaries</li>
|
||||
<li><strong>Serverless</strong> - Custom executable path for lightweight Chromium builds</li>
|
||||
</ul>
|
||||
|
||||
<h2>Example</h2>
|
||||
<CodeBlock code={`# Navigate and get snapshot
|
||||
agent-browser open example.com
|
||||
agent-browser snapshot -i
|
||||
|
||||
# Output:
|
||||
# - heading "Example Domain" [ref=e1]
|
||||
# - link "More information..." [ref=e2]
|
||||
|
||||
# Interact using refs
|
||||
agent-browser click @e2
|
||||
agent-browser screenshot page.png
|
||||
agent-browser close`} />
|
||||
|
||||
<h2>Why refs?</h2>
|
||||
<p>
|
||||
The <code>snapshot</code> command returns an accessibility tree where each element
|
||||
has a unique ref like <code>@e1</code>, <code>@e2</code>. This provides:
|
||||
</p>
|
||||
<ul>
|
||||
<li><strong>Deterministic</strong> - Ref points to exact element from snapshot</li>
|
||||
<li><strong>Fast</strong> - No DOM re-query needed</li>
|
||||
<li><strong>AI-friendly</strong> - LLMs can reliably parse and use refs</li>
|
||||
</ul>
|
||||
|
||||
<h2>Architecture</h2>
|
||||
<p>
|
||||
Client-daemon architecture for optimal performance:
|
||||
</p>
|
||||
<ol>
|
||||
<li><strong>Rust CLI</strong> - Parses commands, communicates with daemon</li>
|
||||
<li><strong>Node.js Daemon</strong> - Manages Playwright browser instance</li>
|
||||
<li><strong>Fallback</strong> - Uses Node.js directly if native binary unavailable</li>
|
||||
</ol>
|
||||
<p>
|
||||
Daemon starts automatically and persists between commands.
|
||||
</p>
|
||||
|
||||
<h2>Platforms</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Platform</th>
|
||||
<th>Binary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td>macOS ARM64</td><td>Native Rust</td></tr>
|
||||
<tr><td>macOS x64</td><td>Native Rust</td></tr>
|
||||
<tr><td>Linux ARM64</td><td>Native Rust</td></tr>
|
||||
<tr><td>Linux x64</td><td>Native Rust</td></tr>
|
||||
<tr><td>Windows x64</td><td>Native Rust</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function QuickStart() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Quick Start</h1>
|
||||
|
||||
<h2>Basic workflow</h2>
|
||||
<CodeBlock code={`agent-browser open example.com
|
||||
agent-browser snapshot # Get accessibility tree with refs
|
||||
agent-browser click @e2 # Click by ref from snapshot
|
||||
agent-browser fill @e3 "test@example.com" # Fill by ref
|
||||
agent-browser get text @e1 # Get text by ref
|
||||
agent-browser screenshot page.png
|
||||
agent-browser close`} />
|
||||
|
||||
<h2>Traditional selectors</h2>
|
||||
<p>CSS selectors and semantic locators also supported:</p>
|
||||
<CodeBlock code={`agent-browser click "#submit"
|
||||
agent-browser fill "#email" "test@example.com"
|
||||
agent-browser find role button click --name "Submit"`} />
|
||||
|
||||
<h2>AI workflow</h2>
|
||||
<p>Optimal workflow for AI agents:</p>
|
||||
<CodeBlock code={`# 1. Navigate and get snapshot
|
||||
agent-browser open example.com
|
||||
agent-browser snapshot -i --json # AI parses tree and refs
|
||||
|
||||
# 2. AI identifies target refs from snapshot
|
||||
# 3. Execute actions using refs
|
||||
agent-browser click @e2
|
||||
agent-browser fill @e3 "input text"
|
||||
|
||||
# 4. Get new snapshot if page changed
|
||||
agent-browser snapshot -i --json`} />
|
||||
|
||||
<h2>Headed mode</h2>
|
||||
<p>Show browser window for debugging:</p>
|
||||
<CodeBlock code="agent-browser open example.com --headed" />
|
||||
|
||||
<h2>JSON output</h2>
|
||||
<p>Use <code>--json</code> for machine-readable output:</p>
|
||||
<CodeBlock code={`agent-browser snapshot --json
|
||||
agent-browser get text @e1 --json
|
||||
agent-browser is visible @e2 --json`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Selectors() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Selectors</h1>
|
||||
|
||||
<h2>Refs (recommended)</h2>
|
||||
<p>
|
||||
Refs provide deterministic element selection from snapshots. Best for AI agents.
|
||||
</p>
|
||||
<CodeBlock code={`# 1. Get snapshot with refs
|
||||
agent-browser snapshot
|
||||
# Output:
|
||||
# - heading "Example Domain" [ref=e1] [level=1]
|
||||
# - button "Submit" [ref=e2]
|
||||
# - textbox "Email" [ref=e3]
|
||||
# - link "Learn more" [ref=e4]
|
||||
|
||||
# 2. Use refs to interact
|
||||
agent-browser click @e2 # Click the button
|
||||
agent-browser fill @e3 "test@example.com" # Fill the textbox
|
||||
agent-browser get text @e1 # Get heading text
|
||||
agent-browser hover @e4 # Hover the link`} />
|
||||
|
||||
<h3>Why refs?</h3>
|
||||
<ul>
|
||||
<li><strong>Deterministic</strong> - Ref points to exact element from snapshot</li>
|
||||
<li><strong>Fast</strong> - No DOM re-query needed</li>
|
||||
<li><strong>AI-friendly</strong> - LLMs can reliably parse and use refs</li>
|
||||
</ul>
|
||||
|
||||
<h2>CSS selectors</h2>
|
||||
<CodeBlock code={`agent-browser click "#id"
|
||||
agent-browser click ".class"
|
||||
agent-browser click "div > button"
|
||||
agent-browser click "[data-testid='submit']"`} />
|
||||
|
||||
<h2>Text & XPath</h2>
|
||||
<CodeBlock code={`agent-browser click "text=Submit"
|
||||
agent-browser click "xpath=//button[@type='submit']"`} />
|
||||
|
||||
<h2>Semantic locators</h2>
|
||||
<p>Find elements by role, label, or other semantic properties:</p>
|
||||
<CodeBlock code={`agent-browser find role button click --name "Submit"
|
||||
agent-browser find label "Email" fill "test@test.com"
|
||||
agent-browser find placeholder "Search..." fill "query"
|
||||
agent-browser find testid "submit-btn" click`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Sessions() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Sessions</h1>
|
||||
<p>Run multiple isolated browser instances:</p>
|
||||
<CodeBlock code={`# Different sessions
|
||||
agent-browser --session agent1 open site-a.com
|
||||
agent-browser --session agent2 open site-b.com
|
||||
|
||||
# Or via environment variable
|
||||
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"
|
||||
|
||||
# List active sessions
|
||||
agent-browser session list
|
||||
# Output:
|
||||
# Active sessions:
|
||||
# -> default
|
||||
# agent1
|
||||
|
||||
# Show current session
|
||||
agent-browser session`} />
|
||||
|
||||
<h2>Session isolation</h2>
|
||||
<p>Each session has its own:</p>
|
||||
<ul>
|
||||
<li>Browser instance</li>
|
||||
<li>Cookies and storage</li>
|
||||
<li>Navigation history</li>
|
||||
<li>Authentication state</li>
|
||||
</ul>
|
||||
|
||||
<h2>Authenticated sessions</h2>
|
||||
<p>
|
||||
Use <code>--headers</code> to set HTTP headers for a specific origin:
|
||||
</p>
|
||||
<CodeBlock code={`# Headers scoped to api.example.com only
|
||||
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'
|
||||
|
||||
# Requests to api.example.com include the auth header
|
||||
agent-browser snapshot -i --json
|
||||
agent-browser click @e2
|
||||
|
||||
# Navigate to another domain - headers NOT sent
|
||||
agent-browser open other-site.com`} />
|
||||
<p>Useful for:</p>
|
||||
<ul>
|
||||
<li><strong>Skipping login flows</strong> - Authenticate via headers</li>
|
||||
<li><strong>Switching users</strong> - Different auth tokens per session</li>
|
||||
<li><strong>API testing</strong> - Access protected endpoints</li>
|
||||
<li><strong>Security</strong> - Headers scoped to origin, not leaked</li>
|
||||
</ul>
|
||||
|
||||
<h2>Multiple origins</h2>
|
||||
<CodeBlock code={`agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
|
||||
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'`} />
|
||||
|
||||
<h2>Global headers</h2>
|
||||
<p>For headers on all domains:</p>
|
||||
<CodeBlock code={`agent-browser set headers '{"X-Custom-Header": "value"}'`} />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
import { CodeBlock } from "@/components/code-block";
|
||||
|
||||
export default function Snapshots() {
|
||||
return (
|
||||
<div className="max-w-2xl mx-auto px-4 sm:px-6 py-8 sm:py-12">
|
||||
<div className="prose">
|
||||
<h1>Snapshots</h1>
|
||||
<p>
|
||||
The <code>snapshot</code> command returns the accessibility tree with refs for AI-friendly interaction.
|
||||
</p>
|
||||
|
||||
<h2>Options</h2>
|
||||
<p>Filter output to reduce size:</p>
|
||||
<CodeBlock code={`agent-browser snapshot # Full accessibility tree
|
||||
agent-browser snapshot -i # Interactive elements only
|
||||
agent-browser snapshot -c # Compact (remove empty elements)
|
||||
agent-browser snapshot -d 3 # Limit depth to 3 levels
|
||||
agent-browser snapshot -s "#main" # Scope to CSS selector
|
||||
agent-browser snapshot -i -c -d 5 # Combine options`} />
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Option</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>-i, --interactive</code></td>
|
||||
<td>Only interactive elements (buttons, links, inputs)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>-c, --compact</code></td>
|
||||
<td>Remove empty structural elements</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>-d, --depth</code></td>
|
||||
<td>Limit tree depth</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>-s, --selector</code></td>
|
||||
<td>Scope to CSS selector</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2>Output format</h2>
|
||||
<CodeBlock code={`agent-browser snapshot
|
||||
# Output:
|
||||
# - heading "Example Domain" [ref=e1] [level=1]
|
||||
# - button "Submit" [ref=e2]
|
||||
# - textbox "Email" [ref=e3]
|
||||
# - link "Learn more" [ref=e4]`} />
|
||||
|
||||
<h2>JSON output</h2>
|
||||
<p>Use <code>--json</code> for machine-readable output:</p>
|
||||
<CodeBlock code={`agent-browser snapshot --json
|
||||
# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}`} />
|
||||
|
||||
<h2>Best practices</h2>
|
||||
<ol>
|
||||
<li>Use <code>-i</code> to reduce output to actionable elements</li>
|
||||
<li>Use <code>--json</code> for structured parsing</li>
|
||||
<li>Re-snapshot after page changes to get updated refs</li>
|
||||
<li>Scope with <code>-s</code> for specific page sections</li>
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
import { codeToHtml } from "shiki";
|
||||
|
||||
interface CodeBlockProps {
|
||||
code: string;
|
||||
lang?: string;
|
||||
}
|
||||
|
||||
export async function CodeBlock({ code, lang = "bash" }: CodeBlockProps) {
|
||||
const html = await codeToHtml(code.trim(), {
|
||||
lang,
|
||||
theme: "github-dark-default",
|
||||
});
|
||||
|
||||
return (
|
||||
<div
|
||||
className="code-block"
|
||||
dangerouslySetInnerHTML={{ __html: html }}
|
||||
/>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
"use client";
|
||||
|
||||
import Link from "next/link";
|
||||
import { usePathname } from "next/navigation";
|
||||
import { useState, useEffect } from "react";
|
||||
|
||||
const navigation = [
|
||||
{ name: "Introduction", href: "/" },
|
||||
{ name: "Installation", href: "/installation" },
|
||||
{ name: "Quick Start", href: "/quick-start" },
|
||||
{ name: "Commands", href: "/commands" },
|
||||
{ name: "Selectors", href: "/selectors" },
|
||||
{ name: "Sessions", href: "/sessions" },
|
||||
{ name: "Snapshots", href: "/snapshots" },
|
||||
{ name: "Agent Mode", href: "/agent-mode" },
|
||||
{ name: "CDP Mode", href: "/cdp-mode" },
|
||||
];
|
||||
|
||||
export function Sidebar() {
|
||||
const pathname = usePathname();
|
||||
const [isOpen, setIsOpen] = useState(false);
|
||||
|
||||
useEffect(() => {
|
||||
setIsOpen(false);
|
||||
}, [pathname]);
|
||||
|
||||
useEffect(() => {
|
||||
const handleEscape = (e: KeyboardEvent) => {
|
||||
if (e.key === "Escape") setIsOpen(false);
|
||||
};
|
||||
document.addEventListener("keydown", handleEscape);
|
||||
return () => document.removeEventListener("keydown", handleEscape);
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<>
|
||||
{/* Mobile header */}
|
||||
<header className="lg:hidden fixed top-0 left-0 right-0 z-50 bg-black/90 backdrop-blur-sm border-b border-[#222] px-4 py-3">
|
||||
<div className="flex items-center justify-between">
|
||||
<Link href="/" className="text-sm font-medium">
|
||||
agent-browser
|
||||
</Link>
|
||||
<button
|
||||
onClick={() => setIsOpen(!isOpen)}
|
||||
className="p-2 -mr-2 text-[#888] hover:text-white transition-colors"
|
||||
aria-label="Toggle menu"
|
||||
>
|
||||
{isOpen ? (
|
||||
<svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M6 18L18 6M6 6l12 12" />
|
||||
</svg>
|
||||
) : (
|
||||
<svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
||||
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M4 6h16M4 12h16M4 18h16" />
|
||||
</svg>
|
||||
)}
|
||||
</button>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{/* Mobile overlay */}
|
||||
{isOpen && (
|
||||
<div
|
||||
className="lg:hidden fixed inset-0 z-40 bg-black/80"
|
||||
onClick={() => setIsOpen(false)}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Sidebar */}
|
||||
<aside
|
||||
className={`
|
||||
fixed lg:sticky top-0 left-0 z-50 lg:z-auto
|
||||
w-56 lg:w-48 h-screen
|
||||
bg-black border-r border-[#222]
|
||||
transform transition-transform duration-150 ease-out
|
||||
${isOpen ? "translate-x-0" : "-translate-x-full lg:translate-x-0"}
|
||||
pt-14 lg:pt-0
|
||||
`}
|
||||
>
|
||||
<div className="h-full overflow-y-auto p-5">
|
||||
{/* Desktop header */}
|
||||
<div className="mb-8 hidden lg:block">
|
||||
<Link href="/" className="text-sm font-medium">
|
||||
agent-browser
|
||||
</Link>
|
||||
</div>
|
||||
|
||||
<nav className="space-y-0.5">
|
||||
{navigation.map((item) => {
|
||||
const isActive = pathname === item.href;
|
||||
|
||||
return (
|
||||
<Link
|
||||
key={item.name}
|
||||
href={item.href}
|
||||
className={`block px-2 py-1.5 text-[13px] transition-colors ${
|
||||
isActive
|
||||
? "text-white"
|
||||
: "text-[#666] hover:text-[#999]"
|
||||
}`}
|
||||
>
|
||||
{item.name}
|
||||
</Link>
|
||||
);
|
||||
})}
|
||||
</nav>
|
||||
|
||||
<div className="mt-8 pt-4 border-t border-[#222] space-y-0.5">
|
||||
<a
|
||||
href="https://github.com/vercel-labs/agent-browser"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="block px-2 py-1.5 text-[13px] text-[#666] hover:text-[#999] transition-colors"
|
||||
>
|
||||
GitHub
|
||||
</a>
|
||||
<a
|
||||
href="https://www.npmjs.com/package/agent-browser"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
className="block px-2 py-1.5 text-[13px] text-[#666] hover:text-[#999] transition-colors"
|
||||
>
|
||||
npm
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</aside>
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2017",
|
||||
"lib": ["dom", "dom.iterable", "esnext"],
|
||||
"allowJs": true,
|
||||
"skipLibCheck": true,
|
||||
"strict": true,
|
||||
"noEmit": true,
|
||||
"esModuleInterop": true,
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"jsx": "react-jsx",
|
||||
"incremental": true,
|
||||
"plugins": [
|
||||
{
|
||||
"name": "next"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"@/*": ["./src/*"]
|
||||
}
|
||||
},
|
||||
"include": [
|
||||
"next-env.d.ts",
|
||||
"**/*.ts",
|
||||
"**/*.tsx",
|
||||
".next/types/**/*.ts",
|
||||
".next/dev/types/**/*.ts",
|
||||
"**/*.mts"
|
||||
],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
Reference in New Issue
Block a user