tabbit-browser-devtools-skill

Tabbit Browser DevTools Skill

Skill by ara.so — Devtools Skills collection.

Overview

Tabbit Browser DevTools Skill enables AI agents to discover and connect to a running Tabbit browser instance through its Chrome DevTools Protocol (CDP) endpoint. Tabbit is a Chromium-based browser, and this skill acts as a bridge that:

1. Locates Tabbit's DevToolsActivePort file on the filesystem
2. Extracts the WebSocket endpoint URL
3. Passes that endpoint to agent-browser for actual automation
4. Allows the agent to perform page operations (navigate, click, extract, execute scripts)

This skill does not implement browser automation itself—it delegates to agent-browser while providing the Tabbit-specific connection details.

Prerequisites

Before using this skill, ensure:

• Python 3 is installed
• Node.js/npx is available, or agent-browser is installed globally
• Tabbit browser is installed and running
• Remote debugging is enabled in Tabbit: navigate to tabbit://inspect/#remote-debugging and enable it

Installation

Option 1: Using Skills CLI (Recommended)

npx skills add Tabbit-Browser/Tabbit-Devtools-Skill

Install only the tabbit-devtools skill:

npx skills add Tabbit-Browser/Tabbit-Devtools-Skill --skill tabbit-devtools

Option 2: Install in Codex

In a Codex conversation:

$skill-installer install https://github.com/Tabbit-Browser/Tabbit-Devtools-Skill/tree/main/skills/tabbit-devtools

Or from terminal:

mkdir -p ~/.agents/skills
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --url https://github.com/Tabbit-Browser/Tabbit-Devtools-Skill/tree/main/skills/tabbit-devtools \
  --dest ~/.agents/skills

Option 3: Manual Installation

mkdir -p ~/.agents/skills
ln -sfn /path/to/Tabbit-Devtools-Skill/skills/tabbit-devtools ~/.agents/skills/tabbit-devtools

Always restart your agent after installation.

Installing agent-browser

This skill depends on agent-browser for actual browser operations. Install it:

npx skills add vercel-labs/agent-browser

Or ensure agent-browser is available via npm:

npm install -g agent-browser

The skill will attempt to run agent-browser or npx agent-browser by default.

How It Works

Discovery Process

The skill searches for DevToolsActivePort in these locations (in order):

macOS:

• ~/Library/Application Support/Tabbit/DevToolsActivePort
• ~/Library/Application Support/Tabbit Browser/DevToolsActivePort

Windows:

• %LOCALAPPDATA%\Tabbit Browser\User Data\DevToolsActivePort
• %APPDATA%\Tabbit\User Data\DevToolsActivePort

The DevToolsActivePort file contains two lines:

<port>
<browser-target-id>

Extracting the WebSocket Endpoint

import os
import json
import urllib.request

# Example: reading DevToolsActivePort
port_file = os.path.expanduser("~/Library/Application Support/Tabbit/DevToolsActivePort")

with open(port_file, 'r') as f:
    port = f.readline().strip()

# Query the DevTools JSON endpoint
url = f"http://127.0.0.1:{port}/json/version"
response = urllib.request.urlopen(url)
data = json.loads(response.read())

ws_endpoint = data['webSocketDebuggerUrl']
print(f"WebSocket endpoint: {ws_endpoint}")

Connecting with agent-browser

Once the WebSocket endpoint is discovered, the skill invokes:

agent-browser --cdp ws://127.0.0.1:9222/devtools/browser/<id>

From that point, all browser operations go through agent-browser.

Configuration

Custom agent-browser Binary

If your environment uses a different command to launch agent-browser, set:

export AGENT_BROWSER_BIN="npx --yes agent-browser"

Or for a custom path:

export AGENT_BROWSER_BIN="/usr/local/bin/my-agent-browser"

The skill will use this variable when spawning agent-browser.

Common Patterns

Pattern 1: Discover and Connect

#!/usr/bin/env python3
import os
import json
import urllib.request
import subprocess

# Search for DevToolsActivePort
possible_paths = [
    os.path.expanduser("~/Library/Application Support/Tabbit/DevToolsActivePort"),
    os.path.expanduser("~/Library/Application Support/Tabbit Browser/DevToolsActivePort"),
]

port_file = None
for path in possible_paths:
    if os.path.exists(path):
        port_file = path
        break

if not port_file:
    print("Tabbit is not running or remote debugging is not enabled")
    exit(1)

with open(port_file, 'r') as f:
    port = f.readline().strip()

# Get WebSocket endpoint
url = f"http://127.0.0.1:{port}/json/version"
response = urllib.request.urlopen(url)
version_data = json.loads(response.read())
ws_endpoint = version_data['webSocketDebuggerUrl']

print(f"Found Tabbit at {ws_endpoint}")

# Launch agent-browser with CDP endpoint
agent_browser_bin = os.getenv("AGENT_BROWSER_BIN", "agent-browser")
subprocess.run([agent_browser_bin, "--cdp", ws_endpoint])

Pattern 2: Open a Page

Once connected via agent-browser, the agent can issue commands like:

agent-browser --cdp <ws_endpoint> open https://example.com

Or in Python using subprocess:

import subprocess

ws_endpoint = "ws://127.0.0.1:9222/devtools/browser/abc123"
agent_browser = os.getenv("AGENT_BROWSER_BIN", "agent-browser")

subprocess.run([
    agent_browser,
    "--cdp", ws_endpoint,
    "open", "https://example.com"
])

Pattern 3: Click and Extract

# Click a button
agent-browser --cdp <ws_endpoint> click "button[type='submit']"

# Extract text
agent-browser --cdp <ws_endpoint> extract "h1"

Pattern 4: Execute JavaScript

agent-browser --cdp <ws_endpoint> execute "document.title"

In Python:

result = subprocess.run([
    agent_browser,
    "--cdp", ws_endpoint,
    "execute", "document.querySelector('h1').innerText"
], capture_output=True, text=True)

print(result.stdout)

Troubleshooting

Issue: "DevToolsActivePort not found"

Cause: Tabbit is not running, or remote debugging is disabled.

Solution:

1. Launch Tabbit browser
2. Navigate to tabbit://inspect/#remote-debugging
3. Enable remote debugging
4. Restart Tabbit if necessary

Issue: "Connection refused" when accessing DevTools endpoint

Cause: The port in DevToolsActivePort may be stale, or a firewall is blocking localhost connections.

Solution:

• Restart Tabbit to regenerate the port
• Check firewall settings for localhost access
• Verify the port is correct:

PORT=$(head -n1 ~/Library/Application\ Support/Tabbit/DevToolsActivePort)
curl http://127.0.0.1:$PORT/json/version

Issue: "agent-browser: command not found"

Cause: agent-browser is not installed or not in PATH.

Solution:

npm install -g agent-browser

Or use npx:

export AGENT_BROWSER_BIN="npx --yes agent-browser"

Issue: Multiple Tabbit Instances Running

Cause: Multiple Tabbit profiles or instances may create conflicting DevToolsActivePort files.

Solution:

• Close all Tabbit instances except one
• Restart Tabbit with a single profile
• If using multiple profiles, identify the correct user data directory

Issue: Skill finds endpoint but agent-browser fails

Cause: The WebSocket endpoint might be expired or the browser closed the debugging session.

Solution:

• Restart Tabbit
• Re-enable remote debugging
• Check that no other tool is already connected to the same endpoint

Real-World Workflow

#!/usr/bin/env python3
"""
Workflow: Connect to Tabbit, navigate to a page, extract data
"""
import os
import json
import urllib.request
import subprocess
import sys

def find_devtools_port():
    """Locate Tabbit's DevToolsActivePort file."""
    paths = [
        os.path.expanduser("~/Library/Application Support/Tabbit/DevToolsActivePort"),
        os.path.expanduser("~/Library/Application Support/Tabbit Browser/DevToolsActivePort"),
    ]
    
    for path in paths:
        if os.path.exists(path):
            with open(path, 'r') as f:
                return f.readline().strip()
    
    return None

def get_ws_endpoint(port):
    """Query DevTools JSON endpoint for WebSocket URL."""
    url = f"http://127.0.0.1:{port}/json/version"
    try:
        response = urllib.request.urlopen(url)
        data = json.loads(response.read())
        return data['webSocketDebuggerUrl']
    except Exception as e:
        print(f"Failed to get WebSocket endpoint: {e}")
        return None

def run_agent_browser(ws_endpoint, *args):
    """Execute agent-browser command with CDP endpoint."""
    agent_browser = os.getenv("AGENT_BROWSER_BIN", "agent-browser")
    cmd = [agent_browser, "--cdp", ws_endpoint] + list(args)
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout

def main():
    # Step 1: Find Tabbit
    port = find_devtools_port()
    if not port:
        print("Error: Tabbit is not running or debugging is disabled")
        sys.exit(1)
    
    print(f"Found Tabbit on port {port}")
    
    # Step 2: Get WebSocket endpoint
    ws_endpoint = get_ws_endpoint(port)
    if not ws_endpoint:
        sys.exit(1)
    
    print(f"WebSocket endpoint: {ws_endpoint}")
    
    # Step 3: Navigate to a page
    print("Opening example.com...")
    run_agent_browser(ws_endpoint, "open", "https://example.com")
    
    # Step 4: Extract page title
    print("Extracting page title...")
    title = run_agent_browser(ws_endpoint, "execute", "document.title")
    print(f"Page title: {title.strip()}")
    
    # Step 5: Extract all links
    print("Extracting links...")
    links = run_agent_browser(ws_endpoint, "extract", "a")
    print(f"Links found:\n{links}")

if __name__ == "__main__":
    main()

Agent-Browser Commands

Once connected via --cdp, you have access to all agent-browser commands:

Command	Description	Example
open <url>	Navigate to URL	open https://example.com
click <selector>	Click element	click button.submit
type <selector> <text>	Type into input	type input[name=q] "search term"
extract <selector>	Extract text/HTML	extract h1
execute <js>	Run JavaScript	execute document.title
screenshot	Capture screenshot	screenshot
wait <selector>	Wait for element	wait div.loaded

For full documentation, see: https://github.com/vercel-labs/agent-browser

Summary

This skill provides the glue between Tabbit's CDP endpoint and agent-browser. As an agent, when a user asks to "connect to Tabbit" or "automate Tabbit browser":

1. Use the Python discovery logic to find DevToolsActivePort
2. Extract the WebSocket endpoint
3. Invoke agent-browser --cdp <ws_endpoint> with appropriate commands
4. All page operations are handled by agent-browser

The skill itself is a connector, not a full browser automation framework. It solves the problem of finding and connecting to a running Tabbit instance, then delegates the heavy lifting to the official agent-browser tool.