Browser Tools Skill

Browser Tools - Lightweight Browser Automation

A token-efficient alternative to MCP servers for browser automation. Uses simple CLI tools that leverage your existing bash knowledge.

Inspired by: Mario Zechner's "What if you don't need MCP at all?"

Why Browser Tools?

Traditional MCP servers for browser automation have significant downsides:

• 🐌 Consume 13,700-18,000 tokens just for documentation
• 🤯 Offer 21-26 tools that can confuse AI agents
• 🔒 Lack composability - all outputs must pass through agent context
• 😓 Hard to extend and customize

Browser Tools solves this:

• ⚡ Uses only ~225 tokens for documentation
• 🧠 Leverages existing bash knowledge
• 🔗 True Unix composability (pipes, redirects, chaining)
• 🛠️ Trivial to extend with new tools

Features

• 🚀 start - Launch Chrome with remote debugging
• 🌐 navigate - Open URLs in tabs
• ⚙️ evaluate - Execute JavaScript in page context
• 📸 screenshot - Capture page images
• 🎯 pick - Interactive element selector
• 🍪 cookies - Extract HTTP-only cookies

Quick Install

# Clone the repository
git clone https://github.com/timottowitz/browser-tools-skill.git
cd browser-tools-skill

# Run the install script
./install.sh

That's it! The install script will:

1. Install npm dependencies (puppeteer-core)
2. Make all CLI tools executable
3. Add tools to your PATH in ~/.zshrc or ~/.bashrc
4. Display usage examples

Manual Installation

If you prefer manual setup:

# 1. Install dependencies
npm install

# 2. Make tools executable
chmod +x bin/*

# 3. Add to PATH (add this to your ~/.zshrc or ~/.bashrc)
export PATH="$(pwd)/bin:$PATH"

# Or create a permanent location:
mkdir -p ~/.local/bin/browser-tools
cp -r bin/* ~/.local/bin/browser-tools/
export PATH="$HOME/.local/bin/browser-tools:$PATH"

# 4. Reload shell
source ~/.zshrc  # or source ~/.bashrc

Requirements

• Node.js (v14 or higher)
• npm or yarn
• Google Chrome installed at default location:

- macOS: /Applications/Google Chrome.app - Linux: google-chrome in PATH - Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

Usage Examples

Basic Usage

# Start Chrome with debugging
start

# Navigate to a website
navigate https://example.com

# Extract data with JavaScript
evaluate "document.querySelector('h1').textContent"
# Returns: "Example Domain"

# Take a screenshot
screenshot example.png

# Get cookies
cookies --domain=example.com

Real-World Example: Scraping Hacker News

# Start browser and navigate
start
navigate https://news.ycombinator.com

# Scrape top 10 stories
evaluate "Array.from(document.querySelectorAll('.titleline')).slice(0, 10).map(el => ({
  title: el.querySelector('a')?.textContent,
  url: el.querySelector('a')?.href,
  domain: el.querySelector('.sitestr')?.textContent
}))" > hackernews.json

# Process with jq
cat hackernews.json | jq '.[].title'

Unix Composability (The Key Advantage!)

# Scrape, filter, and process
navigate https://example.com/products
evaluate "Array.from(document.querySelectorAll('.product')).map(p => ({
  name: p.querySelector('.name').textContent,
  price: p.querySelector('.price').textContent
}))" | jq '.[] | select(.price | tonumber  affordable-products.json

# Chain multiple operations
start && \
  navigate https://example.com && \
  screenshot full-page.png --full-page && \
  evaluate "document.body.innerHTML" | grep -o 'email@.*\.com' > emails.txt

Visual Testing

# Compare before/after
navigate https://example.com
screenshot before.png --full-page

# Make changes to the site...

navigate https://example.com
screenshot after.png --full-page

Using with Claude Code

If you're using this as a Claude Code skill:

1. Install to ~/.claude/skills/browser-tools/

mkdir -p ~/.claude/skills
git clone https://github.com/timottowitz/browser-tools-skill.git ~/.claude/skills/browser-tools
cd ~/.claude/skills/browser-tools && npm install

1. The skill.md file provides concise documentation for the AI agent

1. Add to PATH in your shell config:

export PATH="$HOME/.claude/skills/browser-tools/bin:$PATH"

Tool Reference

start

Launches Chrome with remote debugging enabled.

start [--profile=]

Options:

• --profile= - Copy and use an existing Chrome profile for authentication

Output: JSON with debugPort, userDataDir, and wsEndpoint

navigate

Opens a URL in Chrome.

navigate  [--new-tab]

Options:

• --new-tab - Open in a new tab instead of current tab

Output: JSON with final URL and page title

evaluate

Executes JavaScript in the page context.

evaluate 
echo "javascript-code" | evaluate

Input: JavaScript code as argument or stdin

Output: JSON result of the JavaScript evaluation

screenshot

Captures page screenshots.

screenshot [output-file] [--full-page]

Options:

• output-file - Path to save screenshot (default: screenshot.png)
• --full-page - Capture entire page instead of viewport

Output: JSON with absolute path and fullPage flag

pick

Interactive element selector with visual overlay.

pick

Usage: Click on page elements to get their selectors

Output: JSON with selector, tag, id, classes, text, and HTML

cookies

Extracts cookies from the current session.

cookies [--domain=]

Options:

• --domain= - Filter cookies by domain

Output: JSON array of cookies including HTTP-only cookies

Extending Browser Tools

Add new tools by creating Node.js scripts in bin/:

#!/usr/bin/env node
const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.connect({
    browserURL: 'http://127.0.0.1:9222',
    defaultViewport: null
  });

  const pages = await browser.pages();
  const page = pages[pages.length - 1];

  // Your automation logic here

  await browser.disconnect();
})();

Make it executable:

chmod +x bin/your-new-tool

Troubleshooting

Chrome won't start

• Ensure Chrome is installed at the default location
• Check if another Chrome instance is using port 9222
• Kill existing Chrome processes: pkill -f "remote-debugging-port=9222"

Connection refused

• Make sure Chrome is running (via start)
• Check that port 9222 is accessible: curl http://127.0.0.1:9222/json

Scripts not found

• Verify PATH is set correctly: echo $PATH | grep browser-tools
• Ensure scripts are executable: ls -la bin/
• Reload your shell: source ~/.zshrc or source ~/.bashrc

Node.js version issues

• Check version: node --version (need v14+)
• Update Node.js: Use nvm, brew, or download from nodejs.org

Token Comparison

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add your tool or enhancement
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details

Credits

• Inspired by Mario Zechner's blog post
• Built for Claude Code
• Uses Puppeteer Core

Related Projects

• MCP (Model Context Protocol)
• Playwright
• Puppeteer

Made with ❤️ for efficient browser automation