Agent Browser Installer

🎯 Overview

Automated installer that sets up the complete agent-browser environment with a single command. Handles all dependencies, creates CLI wrappers, and verifies the installation.

⚡ Execution Rules

When this Skill is invoked, you MUST:

1. Execute immediately - Don't just say "I will install", actually run the commands
2. Use AskUserQuestion tool to confirm installation paths and preferences
3. Use Bash tool to execute all installation commands
4. Use Write tool to create configuration files
5. Show progress and results to the user at each step
6. Verify installation before completing

📋 Installation Workflow

Step 1: Pre-Installation Check

Check system requirements and existing installations:

# Check Node.js version
node --version

# Check npm version
npm --version

# Check if agent-browser is already installed
npm list -g agent-browser 2>/dev/null || echo "Not installed"

# Check available disk space
df -h ~

Requirements:

• Node.js 18+ (required)
• npm 8+ (required)
• 500MB free disk space (recommended)

Step 2: Ask User Preferences

Use AskUserQuestion to gather:

Question 1: Installation Location

• Header: "Install Path"
• Options:
  • Global npm directory (Recommended) - npm install -g
  • Custom directory - User specifies path
• Description: Global installation makes agent-browser available everywhere

Question 2: Browser Download

• Header: "Browser"
• Options:
  • Auto-download Chromium (Recommended) - Playwright will download
  • Use existing Chrome - Connect to Chrome debugging port
  • Manual setup - User will install browser later
• Description: Auto-download ensures compatibility

Question 3: CLI Wrapper

• Header: "CLI Wrapper"
• Options:
  • Create ab alias (Recommended) - Short command for quick access
  • Use full command - agent-browser only
  • Both - Create alias and keep full command
• Description: Alias makes commands shorter and easier to type

Step 3: Install agent-browser

Execute installation based on user preferences:

# Global installation (recommended)
npm install -g agent-browser

# Or custom directory
cd /path/to/custom/dir && npm install agent-browser

Handle common errors:

• Permission denied → Suggest sudo npm install -g agent-browser (Linux/Mac)
• Network timeout → Retry with npm install -g agent-browser --registry=https://registry.npmmirror.com
• Lock file error → Clean npm cache: npm cache clean --force

Step 4: Install Chromium Browser

Download Chromium using Playwright:

# Install Chromium
npx playwright install chromium

# Verify installation
npx playwright --version

Alternative: Manual download (if auto-install fails)

For Windows:

# Create browser directory
mkdir -p ~/playwright-browsers/chromium-1208

# Download browser
curl -L "https://cdn.playwright.dev/chrome-for-testing-public/145.0.7632.6/win64/chrome-win64.zip" -o ~/playwright-browsers/chrome.zip

# Extract
unzip ~/playwright-browsers/chrome.zip -d ~/playwright-browsers/chromium-1208

# Clean up
rm ~/playwright-browsers/chrome.zip

For Linux:

curl -L "https://cdn.playwright.dev/chrome-for-testing-public/145.0.7632.6/linux/chrome-linux64.zip" -o ~/playwright-browsers/chrome.zip
unzip ~/playwright-browsers/chrome.zip -d ~/playwright-browsers/chromium-1208
rm ~/playwright-browsers/chrome.zip

For macOS:

curl -L "https://cdn.playwright.dev/chrome-for-testing-public/145.0.7632.6/mac/chrome-mac64.zip" -o ~/playwright-browsers/chrome.zip
unzip ~/playwright-browsers/chrome.zip -d ~/playwright-browsers/chromium-1208
rm ~/playwright-browsers/chrome.zip

Step 5: Create CLI Wrapper (Optional)

If user chose to create ab alias:

For Linux/macOS:

# Add to ~/.bashrc or ~/.zshrc
echo 'alias ab="agent-browser"' >> ~/.bashrc
source ~/.bashrc

For Windows (Git Bash):

# Add to ~/.bashrc
echo 'alias ab="agent-browser"' >> ~/.bashrc
source ~/.bashrc

For Windows (PowerShell):

# Add to PowerShell profile
Add-Content $PROFILE 'Set-Alias -Name ab -Value agent-browser'
. $PROFILE

Step 6: Create agent-browser Skill

Create the skill directory and SKILL.md:

# Create skill directory
mkdir -p ~/.claude/skills/agent-browser

# Skill will be created using Write tool (see below)

SKILL.md content (use Write tool):

---
name: agent-browser
description: |
  Browser automation CLI tool with session persistence and file upload.
  Triggers when user needs browser automation, web scraping, or page interaction.
  Core functions: (1) Navigate pages (2) Interact with elements (3) Take screenshots (4) Upload files (5) Persist sessions
---

# Agent Browser - Browser Automation Skill

## 🎯 Overview

AI-native browser automation tool built on Playwright. Uses ref-based element selection for 93% less context consumption.

## ⚡ Execution Rules

**When this Skill is invoked, you MUST:**

1. **Execute immediately** - Don't just describe, run the commands
2. **Use Bash tool** to execute agent-browser commands
3. **Show results** to the user
4. **Close browser** when done to avoid session leaks

## 📋 Command Reference

### Navigation
- `agent-browser open <url>` - Navigate to URL
- `agent-browser back` - Go back
- `agent-browser forward` - Go forward
- `agent-browser reload` - Reload page

### Element Interaction
- `agent-browser snapshot -i` - Get interactive elements with refs
- `agent-browser click @ref` - Click element
- `agent-browser fill @ref <text>` - Fill input field
- `agent-browser type @ref <text>` - Type into element
- `agent-browser hover @ref` - Hover over element

### Information Retrieval
- `agent-browser get text <selector>` - Get text content
- `agent-browser get title` - Get page title
- `agent-browser get url` - Get current URL
- `agent-browser screenshot [path]` - Take screenshot

### File Operations
- `agent-browser upload @ref <filepath>` - Upload file

### Session Persistence
- `agent-browser --profile <path> open <url>` - Use persistent profile
- Profile saves cookies, localStorage, and login states

### Browser Control
- `agent-browser close` - Close browser
- `agent-browser connect [endpoint]` - Connect to Chrome debugging port

## 💡 Usage Examples

### Example 1: Simple Navigation
User: "Open Google and take a screenshot"

**Execute immediately:**
```bash
agent-browser open https://google.com
agent-browser screenshot ~/Desktop/google.png
agent-browser close

Example 2: Session Persistence

User: "Login to GitHub and save the session"

Execute immediately:

# First time: login and save
agent-browser --profile ~/.agent-browser/github --headed open https://github.com/login
# (User logs in manually)

# Next time: automatically logged in
agent-browser --profile ~/.agent-browser/github open https://github.com/settings

Example 3: File Upload

User: "Upload my avatar to GitHub profile"

Execute immediately:

agent-browser --profile ~/.agent-browser/github open https://github.com/settings/profile
agent-browser snapshot -i  # Find file input ref (e.g., @e68)
agent-browser upload @e68 "/path/to/avatar.jpg"
agent-browser click @save-button-ref
agent-browser close

Example 4: Form Filling

User: "Fill out the contact form on example.com"

Execute immediately:

agent-browser open https://example.com/contact
agent-browser snapshot -i  # Get form element refs
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "john@example.com"
agent-browser fill @e3 "Hello, this is a test message"
agent-browser click @e4  # Submit button
agent-browser close

🔧 Advanced Features

Batch Operations

Execute multiple commands at once:

agent-browser batch "click @e1" "fill @e2 value" "click @e3"

Connect to Existing Chrome

Use your existing Chrome with all logins:

# Start Chrome with debugging
chrome --remote-debugging-port=9222

# Connect agent-browser
agent-browser connect http://127.0.0.1:9222
agent-browser open https://gmail.com  # Already logged in!

⚠️ Important Notes

1. Always close browser - Use agent-browser close to avoid session leaks
2. Use profiles for persistence - --profile flag saves login states
3. Get refs before interaction - Run snapshot -i before click or fill
4. Absolute paths for files - Use full paths for screenshots and uploads
5. Wait for page load - Add agent-browser wait 2000 if needed

🎯 Trigger Scenarios

Use this skill when user says:

• "Open a webpage..."
• "Browse..."
• "Take a screenshot..."
• "Scrape web content..."
• "Click on..."
• "Fill out a form..."
• "Upload a file..."
• "Automate browser..."

Version: v1.0.0 Status: ✅ Ready to use

### Step 7: Verification

Run comprehensive tests to verify installation:

```bash
# Test 1: Check agent-browser is installed
which agent-browser || echo "❌ agent-browser not found in PATH"

# Test 2: Check version
agent-browser --version || echo "❌ Failed to get version"

# Test 3: Test basic navigation
agent-browser open https://example.com
agent-browser get title
agent-browser close

# Test 4: Test screenshot
agent-browser open https://example.com
agent-browser screenshot /tmp/test-screenshot.png
ls -lh /tmp/test-screenshot.png
agent-browser close

# Test 5: Test snapshot
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close

# Test 6: Check Chromium installation
ls -la ~/playwright-browsers/chromium-*/chrome* || echo "⚠️ Chromium not found"

Verification Checklist:

• ✅ agent-browser command available
• ✅ Version command works
• ✅ Can open webpages
• ✅ Can take screenshots
• ✅ Can get page snapshots
• ✅ Chromium browser installed
• ✅ Skill created in ~/.claude/skills/

Step 8: Generate Installation Report

Create a summary report:

# Agent Browser Installation Report

## ✅ Installation Summary

**Date**: {timestamp}
**Status**: SUCCESS / FAILED

## 📦 Installed Components

- ✅ agent-browser CLI: v{version}
- ✅ Chromium Browser: {browser_version}
- ✅ CLI Wrapper: {ab/full/both}
- ✅ Claude Skill: ~/.claude/skills/agent-browser/

## 🔧 Configuration

- Installation Path: {path}
- Browser Path: {browser_path}
- Profile Directory: ~/.agent-browser/

## 🚀 Quick Start

### Basic Usage
```bash
agent-browser open https://example.com
agent-browser screenshot ~/Desktop/screenshot.png
agent-browser close

With Session Persistence

agent-browser --profile ~/.agent-browser/myprofile open https://github.com

📚 Next Steps

1. Try the examples in the skill documentation
2. Create profiles for different accounts
3. Explore advanced features (batch operations, file upload)

🆘 Troubleshooting

If you encounter issues:

1. Check Node.js version: node --version (need 18+)
2. Verify installation: agent-browser --version
3. Check browser: ls ~/playwright-browsers/
4. See documentation: ~/.claude/skills/agent-browser/SKILL.md

Installation completed successfully! 🎉

## 💡 Usage Examples

### Example 1: Full Installation (Recommended)

User: "Install agent-browser"

**Execute immediately:**

1. Ask user preferences using AskUserQuestion
2. Run pre-installation checks
3. Install agent-browser globally
4. Download Chromium
5. Create `ab` alias
6. Create skill
7. Verify installation
8. Show installation report

### Example 2: Reinstall/Repair

User: "Reinstall agent-browser, it's not working"

**Execute immediately:**

1. Uninstall existing: `npm uninstall -g agent-browser`
2. Clean cache: `npm cache clean --force`
3. Remove browser: `rm -rf ~/playwright-browsers/`
4. Follow full installation workflow
5. Verify installation

### Example 3: Update Installation

User: "Update agent-browser to latest version"

**Execute immediately:**

```bash
# Update agent-browser
npm update -g agent-browser

# Update Chromium
npx playwright install chromium

# Verify versions
agent-browser --version
npx playwright --version

🔧 Troubleshooting Guide

Issue 1: Permission Denied (Linux/Mac)

Error: EACCES: permission denied

Solution:

# Option 1: Use sudo (not recommended)
sudo npm install -g agent-browser

# Option 2: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g agent-browser

Issue 2: Network Timeout

Error: network timeout or ETIMEDOUT

Solution:

# Use mirror registry
npm install -g agent-browser --registry=https://registry.npmmirror.com

# Or increase timeout
npm install -g agent-browser --fetch-timeout=60000

Issue 3: Chromium Download Failed

Error: Failed to download Chromium

Solution: Use manual download (see Step 4 alternative methods)

Issue 4: Command Not Found

Error: agent-browser: command not found

Solution:

# Check npm global bin path
npm config get prefix

# Add to PATH
export PATH="$(npm config get prefix)/bin:$PATH"
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue 5: Playwright Lock File Error

Error: Unable to update lock within the stale threshold

Solution:

# Remove lock files
rm -rf ~/playwright-browsers/__dirlock

# Retry installation
npx playwright install chromium

📚 Post-Installation

Create Your First Profile

# Create profile directory
mkdir -p ~/.agent-browser/github

# Use profile for persistent sessions
agent-browser --profile ~/.agent-browser/github --headed open https://github.com/login

Set Up Environment Variables (Optional)

# Add to ~/.bashrc or ~/.zshrc
export AGENT_BROWSER_PROFILE=~/.agent-browser/default
export AGENT_BROWSER_HEADLESS=true

Test Advanced Features

# Test batch operations
agent-browser open https://example.com
agent-browser batch "snapshot -i" "screenshot /tmp/test.png" "close"

# Test file upload
agent-browser open https://example.com/upload
agent-browser snapshot -i
agent-browser upload @e1 "/path/to/file.pdf"

⚠️ Important Notes

1. Node.js 18+ required - Check with node --version
2. 500MB disk space - For Chromium browser
3. Internet connection - For downloading packages
4. Administrator rights - May be needed for global installation
5. Firewall settings - Allow Node.js and Chromium

🎯 Success Criteria

Installation is successful when:

• ✅ agent-browser --version returns version number
• ✅ agent-browser open https://example.com works
• ✅ Screenshots can be taken
• ✅ Skill appears in ~/.claude/skills/agent-browser/
• ✅ All verification tests pass

Version: v1.0.0 Last Updated: 2026-01-27 Status: ✅ Ready to use