agent browser installer
- Repo stars 4
- Author repo agent-browser-skill
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @00OO666 · no license declared
- Token usage
- Heavy
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Check system requirements and existing installations: Requirements: Node.js 18+ (required) npm 8+ (required) 500MB free disk space (recommended)
Use AskUserQuestion to gather: Question 1: Installation Location Header: "Install Path" Options: Global npm directory (Recommended) - `npm install -g`
Execute installation based on user preferences: 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`
Download Chromium using Playwright: Alternative: Manual download (if auto-install fails) For Windows: For Linux: For macOS:
If user chose to create `ab` alias: For Linux/macOS: For Windows (Git Bash): For Windows (PowerShell):
Create the skill directory and SKILL.md: SKILL.md content (use Write tool): agent-browser open https://google.com agent-browser screenshot ~/Desktop/google.png agent-browser close
Run comprehensive tests to verify installation: Verification Checklist: ✅ agent-browser command available ✅ Version command works ✅ Can open webpages
Create a summary report: agent-browser open https://example.com agent-browser screenshot ~/Desktop/screenshot.png agent-browser close agent-browser --profile ~/.agent-browser/myprofile open https://github.com
# 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:
```bash
# 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:
```bash
# 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:
```bash
# Install Chromium
npx playwright install chromium
# Verify installation
npx playwright --version
```
**Alternative: Manual download (if auto-install fails)**
For Windows:
```bash
# 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:
```bash
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:
```bash
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:**
```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'alias ab="agent-browser"' >> ~/.bashrc
source ~/.bashrc
```
**For Windows (Git Bash):**
```bash
# Add to ~/.bashrc
echo 'alias ab="agent-browser"' >> ~/.bashrc
source ~/.bashrc
```
**For Windows (PowerShell):**
```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:
```bash
# Create skill directory
mkdir -p ~/.claude/skills/agent-browser
# Skill will be created using Write tool (see below)
```
**SKILL.md content** (use Write tool):
```markdown
---
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:**
```bash
# 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:**
```bash
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:**
```bash
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:
```bash
agent-browser batch "click @e1" "fill @e2 value" "click @e3"
```
### Connect to Existing Chrome
Use your existing Chrome with all logins:
```bash
# 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:
```markdown
# 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
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# Remove lock files
rm -rf ~/playwright-browsers/__dirlock
# Retry installation
npx playwright install chromium
```
## 📚 Post-Installation
### Create Your First Profile
```bash
# 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)
```bash
# Add to ~/.bashrc or ~/.zshrc
export AGENT_BROWSER_PROFILE=~/.agent-browser/default
export AGENT_BROWSER_HEADLESS=true
```
### Test Advanced Features
```bash
# 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
Listed in source order.
sections -> 🎯 Overview → ⚡ Execution Rules → 📋 Installation Workflow → Step 1: Pre-Installation Check → Step 2: Ask User Preferences → Step 3: Install agent-browser
terms -> When this Skill is invoked, you MUST · Execute immediately · Use AskUserQuestion tool · Use Bash tool · Use Write tool · Show progress · Verify installation · Requirements
files/cmd -> npm install -g · agent-browser · sudo npm install -g agent-browser · npm install -g agent-browser --registry=https://registry.npmmirror.com · npm cache clean --force · agent-browser open <url> · agent-browser back · agent-browser forward
body sha256 -> 3a81f895e2b8
⚡ Execution Rules
When this Skill is invoked, you MUST: Execute immediately - Don't just say "I will install", actually run the commands Use AskUserQuestion tool to confirm installation paths and preferences Use Bash tool to execute all installation commands Use Write tool to create configuration files
Step 1: Pre-Installation Check
Check system requirements and existing installations: 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 -gStep 3: Install agent-browser
Execute installation based on user preferences: Handle common errors: Permission denied → Suggest
sudo npm install -g agent-browser(Linux/Mac) Network timeout → Retry withnpm install -g agent-browser --registry=https://registry.npmmirror.comLock file error → Clean npm cache:npm cache clean --forceStep 4: Install Chromium Browser
Download Chromium using Playwright: Alternative: Manual download (if auto-install fails) For Windows: For Linux: For macOS: