Chromancer 🧙

A powerful command-line interface for automating Chrome browser using Playwright. Perfect for web scraping, automation, testing, and browser workflows.

✨ What's New

• 🤖 AI-Powered Automation - Natural language commands with AI integration
• 🔍 Intelligent DOM Inspection - Smart selector discovery for robust automation
• 🔄 AI Feedback Loop - Automatic workflow refinement and verification
• 📊 Enhanced Data Extraction - Automatic formatting and file saving
• 🚀 DOM Pipeline Optimizations - Mini digest, selector ranking, and structured logs for 90% better success rates
• 🎭 Playwright-powered - Built on Playwright for superior performance and features
• 📝 YAML Workflows - Write automation scripts in simple YAML with variable support
• 💡 Smart Error Tips - Helpful error messages that teach correct usage
• 🎯 10+ New Commands - Claude, inspect, record, export, fill, scroll, cookies, PDF, network monitoring, and more
• 🚀 Quick Commands - One-line site testing and data extraction
• ⚙️ Config System - Persistent settings and defaults
• 📚 Interactive Examples - Learn by example with categorized recipes

Features

• 🚀 Easy Setup - Onboarding wizard with chromancer init
• 🤖 AI Assistant - Natural language to automation with Claude
• 🔄 Session Management - All commands work with your active Chrome instance
• 🎮 Interactive REPL - Execute commands interactively with history
• 📝 YAML Workflows - Automate complex tasks with simple YAML files
• 🎬 Record & Replay - Record browser interactions and generate scripts
• 📊 Data Export - Extract data as JSON, CSV, HTML, or Markdown
• 🖱️ Smart Automation - Click, type, scroll, fill forms automatically
• 📸 Screenshots & PDFs - Capture pages in multiple formats
• 🍪 Cookie Management - Save and restore browser sessions
• 🌐 Network Monitoring - Track and analyze network requests
• 💡 Helpful Errors - Smart error messages with solutions
• 🔍 DOM Inspector - Intelligent selector discovery

Requirements

• Node.js 18.0.0 or higher
• Chrome or Chromium browser installed

Installation

Global Installation (Recommended)

npm install -g chromancer

Quick Start

# First time? Run the setup wizard
chromancer init

# Start Chrome
chromancer spawn

# Try it out!
chromancer navigate https://example.com
chromancer screenshot example.png

🎯 Core Commands

Browser Control

# Start Chrome with remote debugging
chromancer spawn                    # Opens Chrome
chromancer spawn --headless         # Headless mode
chromancer spawn --profile work     # Use Chrome profile

# Navigate pages
chromancer navigate https://example.com
chromancer go https://example.com   # Alias for navigate

# Stop Chrome
chromancer stop

AI-Powered Natural Language Automation

# Use natural language to control the browser
chromancer ai "click the login button and wait for dashboard"
chromancer ai "scroll down and take a screenshot of the footer"
chromancer ai "extract all product prices from this page"

# Interactive mode with AI feedback loop
chromancer ai "find and click all download links"
# AI will verify results and refine if needed

# Preview generated workflow without executing
chromancer ai --dry-run "fill out the contact form"

# Skip interactive verification
chromancer ai --no-interactive "navigate to settings and click logout"

# Default command - just type your instruction!
chromancer "take a screenshot of the hero section"

🔧 Advanced DOM Pipeline Optimizations

The Claude command includes intelligent DOM analysis and optimization features that automatically activate during workflow generation and refinement:

When it's triggered:

• Automatically when data extraction fails (selectors return 0 items)
• During autofix attempts when previous workflows didn't succeed
• When the --auto-inspect flag is enabled (default: true)

How it works:

1. Mini DOM Digest (~2-3KB)

   • Captures page structure efficiently without overwhelming token limits
   • Collects top element patterns, text samples, and data attributes
   • Caches digest per URL for performance

2. Intelligent Selector Ranking

   • Tests and ranks selectors by confidence score
   • Considers element count, content consistency, and specificity
   • Provides alternative selectors when primary ones fail

3. Structured Run Logs

   • Saves detailed execution results as JSON
   • Tracks selector performance and sample data
   • Enables learning from past successes/failures

4. Enhanced Autofix Loop

   • Feeds actual page structure to Claude during retries
   • Uses ranked selectors for better alternatives
   • Reduces false positives and wasted tokens

Why it matters:

• Higher success rates: Claude gets real page data, not guesses
• Faster iterations: Mini digest reduces token usage by ~90%
• Better debugging: Run logs track exactly what worked/failed
• Smarter retries: Each attempt builds on previous knowledge

Example workflow with optimizations:

# First attempt might fail
chromancer ai "extract all product prices"
# 🔍 DOM inspection automatically activates
# 📊 Generates mini digest with top patterns
# 🎯 AI receives: ".price-tag (47 elements)", ".product-price (23 elements)"
# ✅ Second attempt uses better selectors

Page Interaction

# Click elements
chromancer click "button.submit"
chromancer click "#menu" --right    # Right click

# Type text
chromancer type "input[name=email]" "[email protected]"
chromancer type "#search" "query" --press-enter

# Fill forms automatically
chromancer fill --auto-generate     # Generate test data
chromancer fill --data '{"name": "John", "email": "[email protected]"}'

# Scroll pages
chromancer scroll down
chromancer scroll --to "#footer"
chromancer scroll --by 500          # Pixels

Data Extraction

# Take screenshots
chromancer screenshot page.png
chromancer shot page.png            # Alias

# Generate PDFs
chromancer pdf --output report.pdf --format A4

# Export page data
chromancer export --format json --selector "table"
chromancer export --format csv --output data.csv

# Quick data extraction
chromancer quick extract https://news.site "h2.headline"

# Inspect DOM to find selectors
chromancer inspect "product prices"         # AI-powered selector discovery
chromancer inspect "search results" --json  # Raw inspection data
chromancer inspect "navigation links" --selector "nav"  # Limit scope

Testing & Monitoring

# Quick site check
chromancer quick check example.com

# Comprehensive site test
chromancer quick test example.com   # Tests a11y, performance, mobile, console errors

# Monitor network traffic
chromancer network --filter "api" --type xhr
chromancer network --block "ads" --block "analytics"

# Wait for conditions
chromancer wait --selector ".loaded"
chromancer wait --text "Success"
chromancer wait --url "https://example.com/dashboard"

🤖 AI-Powered Automation with Claude

The Claude command transforms natural language into Chromancer workflows with intelligent feedback and verification:

Key Features

• Natural Language Processing: Write commands in plain English
• Intelligent Feedback Loop: Claude verifies results and automatically refines workflows
• DOM Inspection: Automatically inspects page structure when selectors fail
• Data Extraction: Smart detection and formatting of extracted data
• Workflow Management: Save and reuse successful workflows

Examples

# Basic automation
chromancer ai "go to github.com and click the sign in button"

# Data extraction with automatic formatting
chromancer ai "extract all article headlines and save them as JSON"

# Complex workflows
chromancer ai "login to dashboard, navigate to reports, and download the monthly CSV"

# With verification
chromancer ai "find all product cards and verify each has a price"

Advanced Options

# Preview without executing
chromancer ai --dry-run "fill out the entire registration form"

# Skip interactive feedback
chromancer ai --no-interactive "take screenshots of each section"

# Set maximum retry attempts
chromancer ai "find and click the hidden menu"

# Disable auto DOM inspection
chromancer ai --no-auto-inspect "click the submit button"

How It Works

1. Natural Language → YAML: Claude converts your instruction to a workflow
2. Execution: The workflow runs against your Chrome instance
3. Verification: Claude analyzes the results
4. Refinement: If needed, Claude adjusts and retries
5. Success: Workflow can be saved for future use

📝 YAML Workflows

Create reusable automation scripts with YAML:

Example: Login Workflow

# login.yml
- navigate: https://github.com/login
- type:
    selector: input[name="login"]
    text: ${USERNAME}
- type:
    selector: input[name="password"]
    text: ${PASSWORD}
- click: input[type="submit"]
- wait:
    url: https://github.com
- screenshot: logged-in.png

Run with variables:

chromancer run login.yml --var USERNAME=myuser --var PASSWORD=mypass

Example: Web Scraping

# scrape-news.yml
- navigate: https://news.ycombinator.com
- wait: .itemlist
- evaluate: |
    Array.from(document.querySelectorAll('.athing')).slice(0, 10).map(item => ({
      title: item.querySelector('.titleline a')?.textContent,
      link: item.querySelector('.titleline a')?.href
    }))
- export:
    format: json
    output: news-stories.json

🎬 Recording Browser Actions

Record your interactions and generate automation scripts:

# Start recording
chromancer record --output actions.json

# Perform actions in browser...
# Press Ctrl+C to stop

# Generate JavaScript
chromancer record --output script.js --format js

🍪 Session Management

Save and restore browser sessions:

# Save cookies
chromancer cookies save --output session.json

# Restore cookies
chromancer cookies load --file session.json

# Manage individual cookies
chromancer cookies list
chromancer cookies set sessionId=abc123
chromancer cookies delete trackingId

🔍 DOM Inspection

The inspect command helps you discover working selectors intelligently:

# Find selectors for specific content
chromancer inspect "product prices"
chromancer inspect "article titles"
chromancer inspect "navigation menu"

# Get raw JSON data for advanced analysis
chromancer inspect "search results" --json

# Limit inspection to specific areas
chromancer inspect "prices" --selector ".product-grid"

The inspector provides:

• Common selector patterns
• Page structure analysis
• Tested selector suggestions with element counts
• Sample content from found elements

🎮 Interactive Mode

Start an interactive session for rapid testing:

chromancer interactive

# In the session:
> navigate https://example.com
> click button
> type input "text"
> screenshot test.png
> help              # Show all commands
> exit

⚙️ Configuration

Set persistent defaults:

# View current config
chromancer config list

# Set defaults
chromancer config set chrome.port 9223
chromancer config set commands.screenshot.fullPage true
chromancer config set ui.colorOutput false

# Reset to defaults
chromancer config reset

📚 Learning Resources

Interactive Examples

# List all example categories
chromancer examples --list

# View specific examples
chromancer examples login       # Authentication patterns
chromancer examples scraping    # Data extraction
chromancer examples testing     # Site testing
chromancer examples forms       # Form automation

Quick Commands for Common Tasks

# Quick site check - health, performance, accessibility
chromancer quick check example.com

# Quick screenshot
chromancer quick capture https://example.com screenshot.png

# Quick data extraction
chromancer quick extract https://news.site "article h2" --json

🔧 Advanced Features

Chrome Profiles

Use different Chrome profiles for different tasks:

# Personal browsing
chromancer spawn --profile personal

# Work browsing with saved logins
chromancer spawn --profile work

Wait for Login

Handle authentication flows:

# Navigate and wait for manual login
chromancer wait-for-login https://app.example.com

# With custom ready selector
chromancer wait-for-login https://github.com --ready-selector ".Header-link--profile"

Error Handling in Workflows

# Continue on error
chromancer run workflow.yml --continue-on-error

# Strict mode (default) - stop on first error
chromancer run workflow.yml --strict

💡 Smart Error Messages

Chromancer provides helpful error messages with solutions:

❌ Element not found: button
💡 Tip: Did you forget to add a class (.) or ID (#) prefix?

Example:
   chromancer click ".button" # for class
   chromancer click "#button" # for ID

📚 Docs: https://chromancer.dev/docs/click#errors

🧪 Testing

# Run unit tests
npm test

# Run working features test
node test/test-working-features.js

# Test with Docker Chrome
docker run -d --name chrome-test -p 9222:9222 zenika/alpine-chrome \
  --no-sandbox --remote-debugging-host=0.0.0.0 --remote-debugging-port=9222

Example Workflows

Daily Screenshot

#!/bin/bash
chromancer spawn --headless
chromancer navigate https://dashboard.example.com
chromancer wait --selector ".data-loaded"
chromancer screenshot "dashboard-$(date +%Y%m%d).png"
chromancer stop

Form Testing

# test-registration.yml
- navigate: https://app.example.com/register
- fill:
    form:
      firstName: Test
      lastName: User
      email: [email protected]
      password: SecurePass123!
- click: input[name="terms"]
- screenshot: form-filled.png
- click: button[type="submit"]
- wait:
    text: "Registration successful"

API Monitoring

# Monitor API calls for 30 seconds
chromancer navigate https://app.example.com
chromancer network --filter "/api/" --duration 30000 --output api-calls.json

# Analyze the results
cat api-calls.json | jq '.[] | select(.duration > 1000)'

AI-Powered Web Scraping

# Extract data with natural language
chromancer ai "extract all product names and prices from this page"
# Automatically saves to timestamped JSON file

# Complex data extraction
chromancer ai "find all news articles, get their titles, dates, and first paragraph"

# Table extraction
chromancer ai "extract the pricing table and save it as CSV"

# Multi-step scraping
chromancer ai "go to the blog section, then extract all post titles and links"

# Or use the default command!
chromancer "scrape all email addresses from this page"

Platform Support

• Windows: Full support with automatic Chrome detection
• macOS: Supports Chrome, Chromium, and Chrome Canary
• Linux: Supports system packages and snap packages
• Docker: Works with headless Chrome containers

Troubleshooting

Chrome not found

# Let chromancer find Chrome
chromancer spawn

# Or specify Chrome location
export CHROME_PATH="/path/to/chrome"

Debugging issues

# Use verbose mode for detailed logs
chromancer navigate https://example.com --verbose

# Check Chrome connection
chromancer quick check localhost

Common Issues

• Port in use: Use chromancer stop or specify a different port with --port
• Timeouts: Increase timeout with --timeout 60000
• Selectors not found: Use chromancer select to explore available elements

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © John Lindquist

Acknowledgments

Chromancer is now powered by Playwright for robust browser automation.