homeclaw/IMAGE_GATHERING_GUIDE.md

Image Gathering Guide for SmallClaw

Overview

SmallClaw v3.1 includes integrated image gathering capabilities through the image_extractor_v1 subagent. This allows you to extract image URLs from web pages efficiently.

How It Works

1. Subagent System

The image_extractor_v1 subagent is a specialized agent that:

• Fetches HTML from URLs using web_fetch
• Parses the HTML to find image sources
• Returns a clean list of image URLs (jpg, png, webp, gif)

2. Tool Integration

The subagent is available through the spawn_subagent tool in the server.

Usage Examples

Example 1: Basic Image Extraction

// Call the image_extractor_v1 subagent
const result = await spawnAgent({
  subagent_id: 'image_extractor_v1',
  task_prompt: 'Extract all image URLs from https://example.com',
  create_if_missing: {
    description: 'Extracts image URLs from HTML pages',
    allowed_tools: ['web_fetch'],
    system_instructions: 'You are a specialist in parsing HTML to find image sources.',
    constraints: ['Extract only direct image URLs (jpg, png, webp, gif)'],
    success_criteria: 'A list of image URLs is provided',
    max_steps: 5,
    timeout_ms: 300000,
  },
});

Example 2: Extract Images from Multiple URLs

const urls = [
  'https://example.com',
  'https://news.ycombinator.com',
  'https://x.com',
];

for (const url of urls) {
  const result = await spawnAgent({
    subagent_id: 'image_extractor_v1',
    task_prompt: `Extract all image URLs from ${url}`,
    create_if_missing: {
      description: 'Extracts image URLs from HTML pages',
      allowed_tools: ['web_fetch'],
      system_instructions: 'You are a specialist in parsing HTML to find image sources.',
      constraints: ['Extract only direct image URLs (jpg, png, webp, gif)'],
      success_criteria: 'A list of image URLs is provided',
      max_steps: 5,
      timeout_ms: 300000,
    },
  });
  console.log(`Images from ${url}:`, result.result_text);
}

Example 3: Extract Images with Filters

const result = await spawnAgent({
  subagent_id: 'image_extractor_v1',
  task_prompt: 'Extract all image URLs from https://example.com that are larger than 100KB',
  create_if_missing: {
    description: 'Extracts image URLs from HTML pages',
    allowed_tools: ['web_fetch'],
    system_instructions: 'You are a specialist in parsing HTML to find image sources. Given a URL, fetch it and extract all image URLs.',
    constraints: [
      'Extract only direct image URLs (jpg, png, webp, gif)',
      'Return a clean list of URLs',
      'Filter out small images (less than 100KB)'
    ],
    success_criteria: 'A list of image URLs is provided',
    max_steps: 5,
    timeout_ms: 300000,
  },
});

Available Subagents

image_extractor_v1

• Purpose: Extract image URLs from HTML pages
• Tools: web_fetch
• Constraints: Extract only direct image URLs (jpg, png, webp, gif)
• Success Criteria: A list of image URLs is provided

image_describer

• Purpose: Describe images using AI
• Tools: read_file, write_file
• Constraints: Analyze image content and provide descriptions

Performance Characteristics

• Navigation Time: ~3-4 seconds per URL
• Extraction Time: ~1-2 seconds per URL
• Total Time: ~5-6 seconds per URL
• Memory Usage: Low (subagent runs in separate process)

Best Practices

1. Be Specific: Provide clear URLs and specific instructions
2. Use Filters: Specify image types or sizes to reduce noise
3. Batch Processing: Extract from multiple URLs in sequence
4. Error Handling: Handle cases where extraction fails gracefully

Limitations

• Requires web_fetch tool (no browser automation)
• May not work on sites with complex JavaScript rendering
• Limited to direct image URLs (no thumbnails or resized versions)
• No image downloading or saving functionality

Future Enhancements

Potential improvements:

• Add browser_get_images tool for JavaScript-rendered sites
• Implement image downloading and saving
• Add image metadata extraction (dimensions, alt text, file size)
• Support for batch image extraction from multiple pages
• Image filtering by type, size, and quality

Testing

Run the test suite:

npx tsx tests/test-image-extraction.ts

Files

• workspace/.smallclaw/subagents/image_extractor_v1/ - Subagent configuration
• src/gateway/subagent-manager.ts - Subagent management system
• src/agents/spawner.ts - Agent spawning logic
• tests/test-image-extraction.ts - Test suite