Skip to content
Claudezilla

Introduction

Claudezilla is a native Firefox browser automation bridge for Claude Code, Hermes Agent, Pi Agent, omp, and standard mcp clients. It connects any supported MCP client to Firefox through JSON-RPC, letting agents navigate pages, click elements, fill forms, take screenshots, and inspect the DOM without Chrome or Chromium.

Architecture

Section titled “Architecture”
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│ Claude Code   │  │ Hermes Agent  │  │ Pi Agent      │
└──────┬────────┘  └──────┬────────┘  └──────┬────────┘
       │ JSON-RPC         │ JSON-RPC         │ JSON-RPC
       └──────────────┬────┴─────────────────┘
                      ▼
              ┌──────────────────┐
              │ MCP Server       │
              │ (Node.js/stdio)  │
              └────────┬─────────┘
                       │ Unix socket / pipe
                       ▼
              ┌──────────────────┐
              │ Native Host      │
              │ (stdio)          │
              └────────┬─────────┘
                       │ 4-byte header + JSON
                       ▼
              ┌──────────────────┐
              │ Firefox Extension│
              │ (MV2)            │
              └──────────────────┘
                 Content scripts
                 interact with DOM

Claude Code, Hermes Agent, Pi Agent, omp, and standard mcp clients. all call the same MCP tools, such as firefox_navigate or firefox_screenshot. The MCP server translates these JSON-RPC requests into commands sent over a Unix socket to the native messaging host, which forwards them to the Firefox extension using a 4-byte length-prefixed JSON protocol. The extension executes commands in the browser and returns results through the same chain.

Key Features

Section titled “Key Features”
  • Multi-harness support — Native MCP integration for Claude Code, Hermes Agent, Pi Agent, omp, and standard mcp clients.
  • Lazy and eager tool discovery — Load only firefox_activate initially for token efficiency, or expose the complete catalog at startup for clients that discover tools once.
  • Browser control — Open windows, navigate URLs, manage tabs, close pages
  • Page interaction — Click elements, type text, press keys, scroll, wait for elements
  • Screenshots — Viewport capture with dynamic readiness detection and image compression
  • Page analysis — Structured JSON page state, accessibility snapshots, element inspection
  • JavaScript evaluation — Run expressions in page context with an explicit popup security gate
  • DevTools access — Console logs and network request monitoring
  • Multi-agent coordination — Tab ownership, screenshot mutex, slot reservations, orphan cleanup
  • Focus loops — Persistent iterative development across supported MCP sessions
  • Annotated screenshots — Visual annotations overlaid on captures
  • Domain allowlist — Restrict which domains agents can access
  • Cross-platform — macOS, Linux, and Windows 10/11 support

Next Steps

Section titled “Next Steps”