Metis - AI Browser Assistant

• Website: https://metistech.lovable.app"
• Downloadble link for extension: https://addons.mozilla.org/en-GB/firefox/addon/metis/ (might take upto 24 hours to load due to Mozilla firefox extension policy.)

AI-powered browser automation assistant for Firefox built with TypeScript + Vite + React.

Quick Start

# Make sure you're in the metis folder. If you're not in there, run
cd metis
# Install dependencies
npm install

# Build the extension
npm run build

# Load in Firefox
# 1. Open Firefox Developer Edition or Nightly (recommended)
# 2. Go to: about:debugging#/runtime/this-firefox
# 3. Click "Load Temporary Add-on"
# 4. Select: dist/manifest.json

Development

# Build the extension
npm run build

# After making changes:
# 1. Run npm run build again
# 2. Click "Reload" on the extension in about:debugging
# 3. Refresh any tabs where you want to test content script changes

Project Structure

metis/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── src/
│   ├── background/
│   │   └── index.ts          # Background script (uses ES modules)
│   ├── content/
│   │   └── index.ts          # Content script (uses global browser API)
│   └── sidebar/
│       ├── index.html        # Sidebar HTML
│       ├── main.tsx          # React entry point
│       ├── App.tsx           # Main React component
│       └── styles.css        # Styles
└── public/
    ├── manifest.json         # Extension manifest (Manifest V3)
    └── icons/
        ├── icon-48.png
        └── icon-96.png

Testing

After loading the extension:

1. Open Sidebar: View > Sidebar > Metis
2. Test Background Communication: Click "Ping Background" - should see response with timestamp
3. Test Content Script:
   • Navigate to any webpage
   • Refresh the page (to ensure content script loads)
   • Click "Ping Content" - should see response with URL and title
4. Check Console: Browser Console (Ctrl+Shift+J) shows:
   • [Metis] Background script loaded
   • [Metis] Background script ready and listening for messages
   • [Metis] Content script loaded on: <url> (on each page)

Testing the action executor

1. Open the sidebar: View → Sidebar → Metis.
2. Grant consent: If shown, enable at least one app (e.g. GitHub) and choose a duration, then click "Allow for 1 hour".
3. Load test plan (no LLM needed):
   • In the 🧪 Testing section, click Load test plan.
   • Scroll down: you should see 📋 Plan Summary with 3 actions (OPEN_TAB → GitHub, SCROLL_TO main, HIGHLIGHT header).
4. Run actions:
   • In 🎯 Actions (select to run, then Start), leave the checkboxes checked (or uncheck any you don’t want).
   • Click Start. You should see:
     • A new tab open to GitHub (OPEN_TAB).
     • Activity log entries: Session started → Action 0 OK → Action 1 OK → Action 2 OK → Session ended.
   • For SCROLL_TO and HIGHLIGHT to work, the active tab (the one in focus) must be a normal webpage where the content script runs (e.g. after OPEN_TAB, click the new GitHub tab so it’s active, then run; or run from a tab that’s already on a site like GitHub).
5. Stop: While a run is in progress, click Stop to abort.
6. Citations: If a plan has citations, click a citation button to scroll and highlight that element on the page.

Full flow (with planner): Open a supported site (e.g. github.com) → Get Page Context → enter a prompt → Generate Plan → select actions → Start. Same executor and activity log apply.

Important Notes

Ollama (Local LLM)

When no OpenAI API key is set, Metis uses Ollama. If you get a 403 "Chat is blocked" error, run:

./scripts/start-ollama.sh

This stops any existing Ollama process/Launch Agent, then starts Ollama with OLLAMA_ORIGINS=chrome-extension://*,moz-extension://* so browser extensions can connect.

Firefox Compatibility

• Manifest V3 with module support ("type": "module" in background)
• Background script uses ES module imports (webextension-polyfill)
• Content script uses global browser API (no imports) to avoid module issues
• Tested on Firefox Developer Edition and Nightly

Debugging Tips

• Always check Browser Console (Ctrl+Shift+J), not Web Console
• After reloading extension, refresh tabs to reload content scripts
• Look for [Metis], [Background], [Content], and [Sidebar] log prefixes

Architecture

Message Flow

Sidebar (React) <---> Background Script <---> Content Scripts
                              ↓
                         Extension APIs
                       (tabs, storage, etc.)

Communication

• Sidebar → Background: browser.runtime.sendMessage({ type: 'PING' })
• Sidebar → Content: browser.tabs.sendMessage(tabId, { type: 'CONTENT_PING' })
• Content → Sidebar: Content scripts can use browser.runtime.sendMessage() to background

Adding Features

Background Script

Edit src/background/index.ts to:

• Handle messages from sidebar and content scripts
• Manage extension state
• Access Firefox APIs (tabs, storage, etc.)
• Uses webextension-polyfill for cleaner API

Content Script

Edit src/content/index.ts to:

• Interact with webpage DOM
• Listen for messages from sidebar/background
• Note: Uses globalThis.browser (no imports) for Firefox compatibility

Sidebar UI

Edit src/sidebar/App.tsx to:

• Add React components
• Send messages to background/content
• Display results and controls
• Full React + TypeScript support

Build Output

After npm run build, the dist/ folder contains:

• manifest.json - Extension manifest (V3)
• background/index.js - Background script (ES module)
• content/index.js - Content script (global browser API)
• sidebar/index.html - Sidebar HTML
• assets/ - Bundled React app, CSS, and polyfills
• icons/ - Extension icons

Tech Stack

• TypeScript - Type-safe JavaScript
• React 18 - UI framework
• Vite - Fast build tool
• webextension-polyfill - Promise-based WebExtension API
• Firefox Manifest V3 - Latest extension format with module support