gemma-gem

To install and build Gemma Gem locally, use pnpm. After building, you must load the extension manually into Chrome using Developer Mode.

1. Install dependencies and build the project:

   pnpm install
   pnpm build

2. Open chrome://extensions in Chrome.
3. Enable Developer mode.
4. Click Load unpacked and select the directory: .output/chrome-mv3-dev/.

Gemma Gem acts as an on-device AI assistant that can interact with the current webpage.

1. Navigate to any website.
2. Click the gem icon located in the bottom-right corner of the page to open the chat interface.
3. Wait for the model to load (progress is indicated on the icon and within the chat).
4. Ask questions about the page content or request specific actions (e.g., 'click the login button' or 'summarize this article').

Access settings by clicking the gear icon in the chat header. Available configurations include:

• Model: Switch between Gemma 4 E2B (~500MB) and Gemma 4 E4B (~1.5GB). Selection is persisted.
• Thinking: Toggle native Gemma 4 thinking capabilities.
• Max iterations: Set a cap on the number of tool call loops allowed per request.
• Shortcuts: Rebind keyboard shortcuts for toggling and closing the chat. Click a field to record a new combination. Use the ↺ button to reset to defaults (Alt+G for toggle, Escape for close).
• Clear context: Resets the conversation history for the current page.
• Disable on this site: Disables the extension for the current hostname.

Logs are prefixed with [Gemma Gem]. In development builds, info, debug, and warn logs are active. In production, only error logs are shown.

To inspect specific components:

• Service worker logs: Go to chrome://extensions $\rightarrow$ Gemma Gem $\rightarrow$ "Inspect views: service worker".
• Offscreen document logs: Go to chrome://extensions $\rightarrow$ Gemma Gem $\rightarrow$ "Inspect views: offscreen.html". Note: These are the most useful logs for viewing model loading, prompt construction, token counts, and tool execution.
• Content script logs: Open the standard Browser DevTools Console on the page you are visiting.
• All contexts: Use chrome://inspect#other to see all inspectable extension contexts.

The vite configuration property in defineConfig allows you to customize the build process. For Gemma Gem, the build is configured to support modern JavaScript features and debugging.

Build options:

• target: Set to esnext to support the latest ECMAScript features required by the project.
• sourcemap: Enabled (true) to assist with debugging.
• minify: Disabled (false) to maintain readable code during development/build processes.

export default defineConfig({
  // ...
  vite: () => ({
    build: {
      target: 'esnext',
      sourcemap: true,
      minify: false,
    },
  }),
})

Gemma Gem uses several tools to interact with the browser. These tools run in different parts of the extension architecture depending on their requirements.

| Tool | Description | Runs in |
|------|-------------|---------|
| `read_page_content` | Read text/HTML of the page or a CSS selector | Content script |
| `take_screenshot` | Capture visible page as PNG | Service worker |
| `click_element` | Click an element by CSS selector | Content script |
| `type_text` | Type into an input by CSS selector | Content script |
| `scroll_page` | Scroll up/down by pixel amount | Content script |
| `run_javascript` | Execute JS in the page context with full DOM access | Service worker |

Default keyboard shortcuts for controlling the chat interface:

| Shortcut | Action | Default |
|----------|--------|---------|
| Toggle chat | Open/close the chat overlay from anywhere on the page | `Alt+G` |
| Close chat | Close the overlay when it's open | `Escape` |

Gemma Gem requires a browser with WebGPU support (Chrome 113+ or Edge 113+). The following are estimated minimal requirements for the two available models:

Gemma 4 E2B (~500 MB)

• GPU VRAM / Shared Memory: 4 GB
• System RAM: 6-8 GB

Gemma 4 E4B (~1.5 GB)

• GPU VRAM / Shared Memory: 6 GB
• System RAM: 8-16 GB

Key Technical Requirements:

• GPU Feature: shader-f16 is required.
• Memory Note: At long contexts (128K), the KV cache adds 10-20% memory overhead on top of model weights.

The project supports two execution modes: development and production. You can specify the mode using the --mode flag when running the build or development commands.

• --mode development: Sets the extension name to Gemma Gem [dev].
• --mode production: Sets the extension name to Gemma Gem (default).

If an invalid mode is provided, the configuration will throw an error.

# Example usage (mode is determined by process.argv)
# The exact command depends on your package.json scripts, but follows this pattern:
# node your-script --mode development