ATR Browser Automation Skill

This skill provides browser automation capabilities through ATR's browser server mode. The browser server runs as a daemon process and accepts CLI commands for browser control.

Architecture

Claude Code --> atr CLI (client) --> ATR Server + Browser

The browser runs in visible (non-headless) mode by default for debugging and verification.

Getting Started

Step 1: Check Browser Status and Start if Needed

Before any browser operations, verify the browser server is running:

atr browser status

If the server is not running, start it:

atr browser start

The server stores state at ~/.atr/browser.state which allows subsequent commands to discover the endpoint automatically.

Step 2: Navigate and Interact

Once running, use navigation and interaction commands to control the browser.

Command Categories

Lifecycle Commands

Navigation Commands

Page Management Commands

Interaction Commands

Inspection Commands

Screenshot Note: Use --file to save screenshots to /tmp/ with a timestamped filename (e.g., /tmp/atr-screenshot-20240105-103045.png). Add --full for full-page screenshots. Use --selector / -s to screenshot a specific element by CSS selector (e.g., -s "header", -s "#nav", -s "main > section:nth-child(2)"). Combine --selector with --full to capture an element's full scrollable height. Use --selector-all to screenshot every matching element as numbered PNGs — elements that fail or timeout are skipped (use --timeout <ms> to control per-element timeout, default 30s). Without --file, returns base64-encoded image data.

Debugging Commands

Workflow Pattern

Follow this workflow for browser automation tasks:

1. •

   Ensure Server Running

   bash

   atr browser status || atr browser start
   

2. •

   Navigate to Target

   bash

   atr browser navigate https://example.com
   

3. •

   Inspect Page Elements

   bash

   atr browser snapshot
   

   This returns elements with unique IDs (UIDs) like e0, e1, etc.

4. •

   Interact with Elements Target elements by:

   • •Text content: "Sign In"
   • •UID from snapshot: e5
   • •CSS selector: .submit-button
5. •

   Verify Results

   bash

   atr browser url
   atr browser title
   atr browser screenshot --file
   

6. •

   Cleanup When Done

   bash

   atr browser stop
   

Asking Questions About a Page

Use atr browser ask when you need specific information from a page without flooding your context with raw HTML or snapshot data. A lightweight sub-agent inspects the page using multiple tools and returns a concise text answer.

atr browser ask "What is the main heading on this page?"
atr browser ask "How many items are in the navigation menu?"
atr browser ask "Is there a login form on this page?"

Prefer ask over html or snapshot when:

• •You need a specific fact, not the full page structure
• •You want to keep your context clean for subsequent reasoning
• •The answer can be expressed as a short text response

Using JSON Output

Add --json flag for structured output when parsing is needed:

atr browser snapshot --json
atr browser list-pages --json
atr browser network --json

Element Targeting

The <target> parameter in click, fill, hover, and drag commands accepts:

1. •Element UID: e0, e5 (from snapshot output)
2. •Visible text: "Sign In", "Submit Form"
3. •aria-label: Elements with matching aria-label attribute
4. •data-testid: Elements with matching data-testid attribute
5. •CSS selector: #login-button, .nav-link, header, footer, nav, main > section, div.hero, li:nth-child(2)

Best practice: Use atr browser snapshot first to see available elements and their UIDs.

Keyboard Keys

For press-key command:

• •Named keys: Enter, Tab, Escape, Backspace
• •Modifiers: Control+a, Shift+Tab, Alt+Enter
• •Arrow keys: ArrowUp, ArrowDown, ArrowLeft, ArrowRight

Troubleshooting

Browser won't start:

atr browser status
rm ~/.atr/browser.state  # If stale state
atr browser start

Port already in use:

atr browser start --port 9334

Element not found:

atr browser snapshot --verbose --json

Additional Resources

For complete command reference with all flags, see references/commands-reference.md.