korchasa

FoxCode: Claude Code -> Firefox Bridge

⚠️ Active Development - This project is under heavy development. APIs, configuration, and behavior may change without notice. Expect breaking changes between versions.

Firefox WebExtension giving Claude Code browser automation in your real browser — with your sessions, cookies, and extensions. The agent scripts multi-step scenarios in a single call instead of round-tripping per action.

FoxCode is a two-part system: a Claude Code plugin (MCP server on Node.js) and a Firefox WebExtension (popup eval console + browser automation), connected via WebSocket on localhost.

Usage Patterns

• Test in the browser — verify fixes, check form flows, inspect rendered output — with access to your project's code
• Automate browser operations — fill forms, click through flows, extract data, manage cookies/storage in one evalInBrowser call
• Debug with browser context — inspect DOM or take a snapshot alongside the source, no need to explain what's on screen

Getting Started

Install

Run /plugin in Claude Code — it opens an interactive plugin manager. Add the marketplace korchasa/foxcode in the Marketplaces tab, then install foxcode from the Discover tab.

Or use commands directly:

/plugin marketplace add korchasa/foxcode
/plugin install foxcode@korchasa

Launch

• /foxcode:foxcode-run-project-profile — isolated Firefox via web-ext with project-local profile (.foxcode/firefox-profile/). Self-contained: checks prerequisites, locates extension, caches paths in .foxcode/config.json.
• /foxcode:foxcode-run-user-profile — your own Firefox via about:debugging. Self-contained: checks prerequisites, locates extension, guides manual loading, caches paths in .foxcode/config.json.

Features

• Real browser, real context — your Firefox with existing sessions, cookies, auth, extensions
• Single-call scripting — full JS scenario in one tool call, no round-trip per action
• Rich async API — ~36 helpers for DOM, navigation, tabs, cookies, screenshots, storage, console capture, dialog handling
• Multi-session — multiple Claude Code sessions connect to one browser simultaneously, each on a unique port
• Zero setup — plugin installs via marketplace, MCP server auto-starts, extension auto-connects via URL hash

Architecture

graph LR
  CC["Claude Code<br/>(terminal)"] -->|stdio| MCP["MCP Channel Plugin<br/>(Node.js)"]
  MCP -->|"WebSocket<br/>localhost:8787–8886"| EXT["Firefox Extension<br/>(popup + background)"]
  EXT -->|executeScript| TAB["Active Tab DOM"]
  EXT -->|eval via content script| PAGE["Page JS Context"]

The MCP server binds to a random port in range 8787–8886 and persists it in ~/.foxcode/port. The extension supports multiple simultaneous connections (one per CC session) — auto-connects via URL hash params, or reconnects to saved sessions. No port scanning, no manual settings.

Components

• Channel Plugin (foxcode/channel/) - MCP server (Node.js, ES modules) bridging Claude Code -> extension via WebSocket. Installed as a Claude Code plugin, provides MCP tools
• Firefox Extension (extension/) - Manifest V2 WebExtension: popup eval console (browser_action), background script for WebSocket + code execution, content script for DOM access in page context
• Run Skills (foxcode/skills/) - launch skills for Project Profile and User Profile modes (see Launch)

MCP tools provided to Claude Code

• evalInBrowser(code, timeout?) - execute JS with browser automation API (click, fill, navigate, snapshot, screenshot, cookies, tabs, etc.)
• status() - server telemetry: port, password, projectDir, uptime, connectedClients, launchMode, client info

Launch Flows

Project Profile (/foxcode:foxcode-run-project-profile)

Isolated Firefox via web-ext run, project-local profile (.foxcode/firefox-profile/). Port passed via URL hash — instant connection.

sequenceDiagram
    participant U as User
    participant CC as Claude Code
    participant MCP as MCP Server
    participant WE as web-ext
    participant FF as Firefox (project profile)
    participant EXT as Extension

    U->>CC: Start session
    CC->>MCP: Launch (stdio)
    MCP->>MCP: Bind port (8787–8886)
    MCP->>MCP: Save port to ~/.foxcode/port

    U->>CC: /foxcode:foxcode-run-project-profile
    CC->>MCP: status tool → get port
    CC->>WE: npx web-ext run --start-url "http://localhost:PORT"
    WE->>FF: Launch with extension pre-loaded
    FF->>EXT: Load extension automatically

    EXT->>EXT: background.js: connect()
    EXT->>EXT: getPortFromTabs() → parse hash from connection page URL
    Note over EXT: Port found instantly from URL hash
    EXT->>MCP: WebSocket connect to PORT
    MCP-->>EXT: Connection established
    EXT-->>U: Sidebar ready, connected

User Profile (/foxcode:foxcode-run-user-profile)