dev-browser-claude-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Dev Browser Skill for Claude Code

> Browser automation with **persistent page state**. Write small, focused scripts that build on each other.

## Credits & Attribution

This skill is a fork of [**SawyerHood/dev-browser**](https://github.com/SawyerHood/dev-browser) by [Sawyer Hood](https://github.com/SawyerHood).

The original project provides the core architecture for persistent browser automation with Claude Code. This fork adds project-specific customizations and additional documentation.

## Why This Skill?

Unlike one-shot browser automation:
- **Pages persist** between script executions
- **State is preserved** — cookies, localStorage, DOM changes survive
- **Incremental workflows** — write small scripts, observe results, iterate

## Installation

### Option A: Claude Plugin (Recommended)

```bash
claude plugin add github:wrsmith108/dev-browser-claude-skill
```

### Option B: Manual

```bash
git clone https://github.com/wrsmith108/dev-browser-claude-skill ~/.claude/skills/dev-browser
cd ~/.claude/skills/dev-browser
bun install
```

## Quick Start

### 1. Start the Server

```bash
cd ~/.claude/skills/dev-browser
./server.sh &
# Wait for "Ready" message
```

Use `--headless` for headless mode (no visible browser window).

### 2. Write Scripts

```bash
cd ~/.claude/skills/dev-browser && bun x tsx <<'EOF'
import { connect, waitForPageLoad } from "@/client.js";

const client = await connect("http://localhost:9222");
const page = await client.page("main");

await page.goto("https://example.com");
await waitForPageLoad(page);

console.log({ title: await page.title(), url: page.url() });
await client.disconnect();
EOF
```

## Core Concepts

### Persistent Pages

Pages are named and persist on the server:

```typescript
const page = await client.page("checkout"); // Create or get named page
const pages = await client.list();           // List all pages
await client.close("checkout");              // Close a page
```

### ARIA Snapshots

Discover page elements without knowing the layout:

```typescript
const snapshot = await client.getAISnapshot("main");
console.log(snapshot);
// Output:
// - banner:
//   - link "Home" [ref=e1]
//   - button "Menu" [ref=e2]
// - main:
//   - heading "Welcome" [level=1]
//   - textbox [ref=e3] /placeholder: "Search"

// Interact by ref
const element = await client.selectSnapshotRef("main", "e2");
await element.click();
```

### Screenshots

```typescript
await page.screenshot({ path: "tmp/screenshot.png" });
await page.screenshot({ path: "tmp/full.png", fullPage: true });
```

## Workflow Pattern

1. **Write a script** — do ONE thing (navigate, click, fill)
2. **Run it** — observe output
3. **Evaluate** — did it work? What's the state?
4. **Iterate** — write next script based on results
5. **Repeat** until done

## Client API

```typescript
const client = await connect("http://localhost:9222");
const page = await client.page("name");          // Get or create page
const pages = await client.list();               // List all pages
await client.close("name");                      // Close a page
const snapshot = await client.getAISnapshot("name");     // ARIA tree
const el = await client.selectSnapshotRef("name", "e5"); // Get element
await client.disconnect();                       // Disconnect (pages persist)
```

The `page` object is a standard [Playwright Page](https://playwright.dev/docs/api/class-page).

## Key Principles

1. **Small scripts** — each does ONE thing
2. **Evaluate state** — always log results at the end
3. **Use page names** — descriptive like `"login"`, `"search-results"`
4. **Plain JS in evaluate** — no TypeScript inside `page.evaluate()`
5. **Disconnect to exit** — pages persist on server

## Waiting

```typescript
import { waitForPageLoad } from "@/client.js";

await waitForPageLoad(page);              // Full page load
await page.waitForSelector(".results");   // Wait for element
await page.waitForURL("**/success");      // Wait for URL
```

## Error Recovery

Pages persist after errors. Debug with:

```typescript
await page.screenshot({ path: "tmp/debug.png" });
console.log({
  url: page.url(),
  title: await page.title(),
});
```

## When to Use

| Use Case | Tool |
|----------|------|
| Interactive debugging | Dev Browser |
| CI/CD regression tests | `npm run test:e2e` (Playwright) |
| Visual inspection | Dev Browser screenshots |
| Form automation | Dev Browser |
| Complex multi-step flows | Dev Browser |

## Related Skills

- [docker-claude-skill](https://github.com/wrsmith108/docker-claude-skill) — Container-based development
- [clerk-claude-skill](https://github.com/wrsmith108/clerk-claude-skill) — Authentication patterns
- [varlock-claude-skill](https://github.com/wrsmith108/varlock-claude-skill) — Secrets management

## Original Project

This is a fork of [SawyerHood/dev-browser](https://github.com/SawyerHood/dev-browser). All credit for the original architecture goes to [Sawyer Hood](https://github.com/SawyerHood).

## License

MIT

Dev Browser Skill for Claude Code

Browser automation with persistent page state. Write small, focused scripts that build on each other.

Credits & Attribution

This skill is a fork of SawyerHood/dev-browser by Sawyer Hood.

The original project provides the core architecture for persistent browser automation with Claude Code. This fork adds project-specific customizations and additional documentation.

Why This Skill?

Unlike one-shot browser automation:

Pages persist between script executions
State is preserved — cookies, localStorage, DOM changes survive
Incremental workflows — write small scripts, observe results, iterate

Installation

Option A: Claude Plugin (Recommended)

claude plugin add github:wrsmith108/dev-browser-claude-skill

Option B: Manual

git clone https://github.com/wrsmith108/dev-browser-claude-skill ~/.claude/skills/dev-browser
cd ~/.claude/skills/dev-browser
bun install

Quick Start

1. Start the Server

cd ~/.claude/skills/dev-browser
./server.sh &
# Wait for "Ready" message

Use --headless for headless mode (no visible browser window).

2. Write Scripts

cd ~/.claude/skills/dev-browser && bun x tsx <<'EOF'
import { connect, waitForPageLoad } from "@/client.js";

const client = await connect("http://localhost:9222");
const page = await client.page("main");

await page.goto("https://example.com");
await waitForPageLoad(page);

console.log({ title: await page.title(), url: page.url() });
await client.disconnect();
EOF

Core Concepts

Persistent Pages

Pages are named and persist on the server:

const page = await client.page("checkout"); // Create or get named page
const pages = await client.list();           // List all pages
await client.close("checkout");              // Close a page

ARIA Snapshots

Discover page elements without knowing the layout:

const snapshot = await client.getAISnapshot("main");
console.log(snapshot);
// Output:
// - banner:
//   - link "Home" [ref=e1]
//   - button "Menu" [ref=e2]
// - main:
//   - heading "Welcome" [level=1]
//   - textbox [ref=e3] /placeholder: "Search"

// Interact by ref
const element = await client.selectSnapshotRef("main", "e2");
await element.click();

Screenshots

await page.screenshot({ path: "tmp/screenshot.png" });
await page.screenshot({ path: "tmp/full.png", fullPage: true });

Workflow Pattern

Write a script — do ONE thing (navigate, click, fill)
Run it — observe output
Evaluate — did it work? What's the state?
Iterate — write next script based on results
Repeat until done

Client API

const client = await connect("http://localhost:9222");
const page = await client.page("name");          // Get or create page
const pages = await client.list();               // List all pages
await client.close("name");                      // Close a page
const snapshot = await client.getAISnapshot("name");     // ARIA tree
const el = await client.selectSnapshotRef("name", "e5"); // Get element
await client.disconnect();                       // Disconnect (pages persist)

The page object is a standard Playwright Page.

Key Principles

Small scripts — each does ONE thing
Evaluate state — always log results at the end
Use page names — descriptive like "login", "search-results"
Plain JS in evaluate — no TypeScript inside page.evaluate()
Disconnect to exit — pages persist on server

Waiting

import { waitForPageLoad } from "@/client.js";

await waitForPageLoad(page);              // Full page load
await page.waitForSelector(".results");   // Wait for element
await page.waitForURL("**/success");      // Wait for URL

Error Recovery

Pages persist after errors. Debug with:

await page.screenshot({ path: "tmp/debug.png" });
console.log({
  url: page.url(),
  title: await page.title(),
});

When to Use

Use Case	Tool
Interactive debugging	Dev Browser
CI/CD regression tests	`npm run test:e2e` (Playwright)
Visual inspection	Dev Browser screenshots
Form automation	Dev Browser
Complex multi-step flows	Dev Browser

Related Skills

docker-claude-skill — Container-based development
clerk-claude-skill — Authentication patterns
varlock-claude-skill — Secrets management

Original Project

This is a fork of SawyerHood/dev-browser. All credit for the original architecture goes to Sawyer Hood.

License

MIT