import { pageMetadata } from "@/lib/page-metadata"

export const metadata = pageMetadata("installation")

# Installation

## Global installation (recommended)

Installs the native Rust binary for maximum performance:

```bash
npm install -g agent-browser-stealth
agent-browser install  # Download Chromium
```

This is the fastest option -- commands run through the native Rust CLI directly with sub-millisecond parsing overhead.

## Quick start (no install)

Run directly with `npx` if you want to try it without installing globally:

```bash
npx agent-browser-stealth install   # Download Chromium (first time only)
npx agent-browser-stealth open example.com
```

> **Note:** `npx` routes through Node.js before reaching the Rust CLI, so it is noticeably slower than a global install. For regular use, install globally.

## Project installation (local dependency)

For projects that want to pin the version in `package.json`:

```bash
npm install agent-browser-stealth
npx agent-browser-stealth install
```

Then use via `npx` or `package.json` scripts:

```bash
npx agent-browser-stealth open example.com
```

## Homebrew (macOS)

```bash
brew install agent-browser
agent-browser install  # Download Chromium
```

## From source

```bash
git clone https://github.com/leeguooooo/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native
./bin/agent-browser install
pnpm link --global
```

## Fork versioning

Fork releases use a dual-version format:

- `<upstream>-fork.<fork>`
- Example: `0.14.0-fork.1`

`agent-browser --version` prints the full version and also shows upstream and fork parts for fork builds.

## Linux dependencies

On Linux, install system dependencies:

```bash
agent-browser install --with-deps
# or manually: npx playwright install-deps chromium
```

## Custom browser

Use a custom browser executable instead of bundled Chromium:

- **Serverless** - Use `@sparticuz/chromium` (~50MB vs ~684MB)
- **System browser** - Use existing Chrome installation
- **Custom builds** - Use modified browser builds

```bash
# 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
```

### Serverless example

```typescript
import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser-stealth';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... use browser
}
```

## AI agent setup

agent-browser works with any AI agent out of the box. For richer context:

### AI coding assistants (recommended)

Install the skill for your AI coding assistant:

```bash
npx skills add leeguooooo/agent-browser
```

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository and stays up to date automatically.

> **Do not** copy `SKILL.md` from `node_modules` -- it will become stale as new features are added. Always use `npx skills add` or reference the repository version.

### AGENTS.md / CLAUDE.md

Add to your instructions file:

```markdown
## 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
```