<!--
hoody-browser Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T20:39:09.332Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: cli


Tokens: 7644

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-browser Subskill

## Overview

**hoody-browser** provides headless Chrome browser automation accessible via HTTP through the Hoody CLI. It enables programmatic web browsing, screenshot capture, JavaScript execution, and page content extraction—all from containerized browser instances.

### When to Use

- **Web scraping**: Extract text, HTML, or structured data from web pages
- **Screenshot automation**: Capture visual snapshots of pages or elements
- **PDF generation**: Export web pages as formatted PDF documents
- **JavaScript execution**: Run custom scripts in a browser context
- **Cookie/session management**: Maintain authenticated browsing sessions
- **Network monitoring**: Inspect HTTP requests and responses
- **Debugging**: Access console logs and DevTools URLs

### Philosophy Alignment

hoody-browser follows Hoody's core principles:
- **Container isolation**: Each browser instance runs in its own container
- **CLI-first interface**: All operations via `hoody browser` commands
- **Zero configuration**: Automatic routing, SSL, and authentication
- **Stateful sessions**: Browser instances persist until explicitly stopped

### Key Concepts

| Concept | Description |
|---------|-------------|
| `browser_id` | Unique identifier for a browser instance (required for most commands) |
| Container targeting | Use `-c <container-id>` or `HOODY_CONTAINER` env var |
| Output format | Use `-o json` for machine-readable output |
| Tab management | Multiple tabs per browser instance |

---

## Common Workflows

### 1. Basic Browser Lifecycle

**Start → Navigate → Capture → Stop**

```
# Step 1: Start a browser instance (returns browser_id)
hoody browser start -c my-container -o json
```

```
{
  "browser_id": "br-abc123",
  "status": "ready",
  "devtools_url": "ws://localhost:9222/devtools/browser/..."
}
```

```
# Step 2: Navigate to a URL
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://example.com"
```

```
# Step 3: Capture screenshot
hoody browser screenshot -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "screenshot": "base64-encoded-png-data",
  "format": "png"
}
```

```
# Step 4: Stop the browser instance
hoody browser stop -c my-container --browser-id br-abc123
```

### 2. Page Content Extraction

**Get HTML and visible text from a page**

```
# Navigate to target page
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://example.com/article"

# Extract full HTML
hoody browser html -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "html": "<!DOCTYPE html><html>...</html>",
  "url": "https://example.com/article"
}
```

```
# Extract visible text only
hoody browser text -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "text": "Article title and visible content...",
  "url": "https://example.com/article"
}
```

### 3. JavaScript Execution

**Execute scripts and retrieve results**

```
# Execute JavaScript via GET (simple expressions)
hoody browser eval -c my-container --browser-id br-abc123 --script "document.title" -o json
```

```
{
  "browser_id": "br-abc123",
  "result": "Example Domain",
  "type": "string"
}
```

```
# Execute JavaScript via POST (complex scripts)
hoody browser eval-post -c my-container --browser-id br-abc123 --script "return document.querySelectorAll('a').length" -o json
```

```
{
  "browser_id": "br-abc123",
  "result": 5,
  "type": "number"
}
```

### 4. Tab Management

**Work with multiple tabs**

```
# List all open tabs
hoody browser list -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "tabs": [
    {
      "tab_id": "tab-001",
      "url": "https://example.com",
      "title": "Example Domain",
      "active": true
    }
  ]
}
```

```
# Open new tab via navigate
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://example.org"

# Close specific tab
hoody browser close -c my-container --browser-id br-abc123 --tab-id tab-001
```

### 5. Cookie Management

**Maintain authenticated sessions**

```
# Get current cookies
hoody browser get -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "example.com",
      "path": "/"
    }
  ]
}
```

```
# Set cookies for authentication
hoody browser set -c my-container --browser-id br-abc123 --cookies '[{"name":"auth_token","value":"xyz789","url":"https://example.com"}]'
```

```
# Clear all cookies
hoody browser clear -c my-container --browser-id br-abc123
```

### 6. PDF Export

**Generate PDF from current page**

```
# Navigate to page
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://example.com/report"

# Export as PDF
hoody browser pdf -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "pdf": "base64-encoded-pdf-data",
  "format": "pdf"
}
```

---

## Advanced Operations

### 1. Multi-Step Scraping Workflow

**Extract structured data across multiple pages**

```
# Start browser
hoody browser start -c scraper-container -o json

# Store browser_id from response
BROWSER_ID="br-abc123"

# Navigate to listing page
hoody browser navigate -c scraper-container --browser-id $BROWSER_ID --url "https://example.com/listings"

# Extract all links via JavaScript
hoody browser eval-post -c scraper-container --browser-id $BROWSER_ID --script "
  const links = Array.from(document.querySelectorAll('.listing a'));
  return links.map(a => a.href);
" -o json
```

```
{
  "browser_id": "br-abc123",
  "result": [
    "https://example.com/listing/1",
    "https://example.com/listing/2",
    "https://example.com/listing/3"
  ],
  "type": "object"
}
```

```
# Navigate to each listing and extract details
hoody browser navigate -c scraper-container --browser-id $BROWSER_ID --url "https://example.com/listing/1"

hoody browser eval-post -c scraper-container --browser-id $BROWSER_ID --script "
  return {
    title: document.querySelector('h1').innerText,
    price: document.querySelector('.price').innerText,
    description: document.querySelector('.desc').innerText
  };
" -o json
```

### 2. Error Recovery Pattern

**Handle navigation failures gracefully**

```
# Attempt navigation
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://unreliable-site.com"

# Check page loaded by verifying content
hoody browser eval -c my-container --browser-id br-abc123 --script "document.readyState" -o json
```

```
{
  "browser_id": "br-abc123",
  "result": "complete",
  "type": "string"
}
```

```
# If page failed, restart browser and retry
hoody browser restart -c my-container --browser-id br-abc123

# Retry navigation
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://unreliable-site.com"
```

### 3. Debugging with Console and Network Logs

**Inspect browser activity**

```
# Navigate to page with potential errors
hoody browser navigate -c my-container --browser-id br-abc123 --url "https://example.com/broken-page"

# Check console for errors
hoody browser console -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "messages": [
    {
      "level": "error",
      "text": "Uncaught TypeError: Cannot read property 'x' of undefined",
      "timestamp": 1699123456789
    }
  ]
}
```

```
# Check network requests
hoody browser network -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "entries": [
    {
      "method": "GET",
      "url": "https://example.com/api/data",
      "status": 500,
      "statusText": "Internal Server Error"
    }
  ]
}
```

```
# Get DevTools URL for manual inspection
hoody browser devtools -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "devtools_url": "ws://localhost:9222/devtools/browser/abc123",
  "discovery_url": "http://localhost:9222/json/version"
}
```

### 4. Browsing History Management

**Query and manage navigation history**

```
# Query browsing history
hoody browser query -c my-container -o json
```

```
{
  "entries": [
    {
      "url": "https://example.com",
      "title": "Example Domain",
      "timestamp": 1699123456789
    }
  ],
  "total": 1,
  "page": 1
}
```

```
# Delete specific history entries
hoody browser delete -c my-container --url "https://example.com" --yes

# Delete all history (requires confirmation)
hoody browser delete -c my-container --yes
```

### 5. Performance Considerations

**Optimize browser automation**

| Consideration | Recommendation |
|---------------|----------------|
| Instance reuse | Keep browser instances running for multiple operations |
| Tab cleanup | Close unused tabs to reduce memory usage |
| Screenshot format | Use PNG for quality, JPEG for smaller size |
| Script complexity | Keep eval scripts minimal; avoid infinite loops |
| History limits | Console/network logs capped at 500 entries |

```
# Check browser instance health
hoody browser health -c my-container -o json
```

```
{
  "status": "healthy",
  "uptime": 3600,
  "active_instances": 2
}
```

```
# Get instance metadata for resource monitoring
hoody browser info -c my-container --browser-id br-abc123 -o json
```

```
{
  "browser_id": "br-abc123",
  "browser_name": "Chrome",
  "browser_version": "119.0.0.0",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
  "viewport": {
    "width": 1280,
    "height": 720
  }
}
```

---

## Quick Reference

### Essential Commands

| Command | Description | Required Params |
|---------|-------------|-----------------|
| `hoody browser start` | Create/retrieve instance | `-c <container-id>` |
| `hoody browser stop` | Stop instance | `-c <container-id>`, `--browser-id` |
| `hoody browser restart` | Restart instance | `-c <container-id>`, `--browser-id` |
| `hoody browser navigate` | Navigate to URL | `-c <container-id>`, `--browser-id`, `--url` |
| `hoody browser screenshot` | Capture screenshot | `-c <container-id>`, `--browser-id` |
| `hoody browser eval` | Execute JavaScript | `-c <container-id>`, `--browser-id`, `--script` |
| `hoody browser eval-post` | Execute JavaScript (POST) | `-c <container-id>`, `--browser-id`, `--script` |
| `hoody browser html` | Get page HTML | `-c <container-id>`, `--browser-id` |
| `hoody browser text` | Get page text | `-c <container-id>`, `--browser-id` |
| `hoody browser list` | List tabs | `-c <container-id>`, `--browser-id` |
| `hoody browser close` | Close tab | `-c <container-id>`, `--browser-id` |
| `hoody browser get` | Get cookies | `-c <container-id>`, `--browser-id` |
| `hoody browser set` | Set cookies | `-c <container-id>`, `--browser-id`, `--cookies` |
| `hoody browser clear` | Clear cookies | `-c <container-id>`, `--browser-id` |
| `hoody browser console` | Get console logs | `-c <container-id>`, `--browser-id` |
| `hoody browser network` | Get network logs | `-c <container-id>`, `--browser-id` |
| `hoody browser pdf` | Export PDF | `-c <container-id>`, `--browser-id` |
| `hoody browser shutdown` | Shutdown instance | `-c <container-id>`, `--browser-id` |
| `hoody browser health` | Health check | `-c <container-id>` |
| `hoody browser devtools` | Get DevTools URLs | `-c <container-id>`, `--browser-id` |
| `hoody browser info` | Get instance metadata | `-c <container-id>`, `--browser-id` |
| `hoody browser query` | Query history | `-c <container-id>` |
| `hoody browser delete` | Delete history | `-c <container-id>`, `--yes` |

### Common Flags

| Flag | Description |
|------|-------------|
| `-c <id>` | Target container ID |
| `--browser-id <id>` | Target browser instance |
| `-o json` | JSON output format |
| `--url <url>` | Target URL for navigation; also filters history entries in `delete` |
| `--script <code>` | JavaScript to execute |
| `--cookies <json>` | Cookie array as JSON string |
| `--tab-id <id>` | Target specific tab |
| `--yes` | Skip confirmation prompts |
| `--clear` | Clear logs after retrieval (applies to `console` and `network` commands) |

### Typical Response Formats

**Instance creation:**
```
{
  "browser_id": "string",
  "status": "ready|starting|error",
  "devtools_url": "string"
}
```

**Page content:**
```
{
  "browser_id": "string",
  "html|text": "string",
  "url": "string"
}
```

**JavaScript execution:**
```
{
  "browser_id": "string",
  "result": "any",
  "type": "string|number|boolean|object|array"
}
```

**Tab listing:**
```
{
  "browser_id": "string",
  "tabs": [
    {
      "tab_id": "string",
      "url": "string",
      "title": "string",
      "active": "boolean"
    }
  ]
}
```

**Cookie operations:**
```
{
  "browser_id": "string",
  "cookies": [
    {
      "name": "string",
      "value": "string",
      "domain": "string",
      "path": "string"
    }
  ]
}
```

**Health check:**
```
{
  "status": "healthy|unhealthy",
  "uptime": "number",
  "active_instances": "number"
}
```