Introduction

Welcome to the AIPage documentation!

This is a cross-browser extension that brings AI assistance directly to EduPage. The extension works seamlessly on Chrome, Firefox, and Safari, providing a clean sidebar interface for interacting with multiple AI providers.

Features

Multi-Browser Support: Works on Chrome, Firefox, and Safari
Multiple AI Providers: Support for Gemini, ChatGPT, Claude, Mistral, LM Studio, and Ollama
Anti-Cheat Protection: Automatically blocks tab switch and copy-paste detection during tests
Privacy First: All API keys stored locally, no data collection
Clean Interface: Vercel-inspired design with responsive sidebar

Quick Links

User Guide: Installation and usage instructions
Contributing Guide: Developer documentation
Changelog: Version history
API Reference: TypeScript API documentation

Getting Started

For end users, start with the User Guide to learn how to install and use the extension.

For developers looking to contribute, check out the Contributing Guide for setup instructions and architecture overview.

AIPage Extension

A cross-browser extension for Chrome, Firefox, and Safari that adds an AI-powered sidebar to EduPage, featuring a clean interface and integration with multiple AI providers.

Features

AI chat assistant integrated directly into EduPage
Multi-Browser Support: Works on Chrome, Firefox, and Safari
Clean, responsive design that matches EduPage's aesthetic
Real-time conversations with multiple AI providers (Gemini, ChatGPT, Claude, Mistral, LM Studio, Ollama)
Secure local storage of API credentials
Responsive sidebar that doesn't obscure important UI elements
Anti-Cheat Protection: Automatically blocks tab switch and copy-paste detection during tests
Smart System Prompt: Ensures the AI acts as a helpful assistant that answers correctly

Installation

To install the extension, download the latest build artifacts directly from our GitLab CI pipelines.

Visit the GitLab Pipelines page.
Locate the latest successful pipeline for the main branch (status: Passed).
Click the Download artifacts icon (or access the pipeline details).
Download the artifact for your specific browser job:
- Chrome: Look for the package:chrome job artifact (contains aipage-chrome.zip).
- Firefox: Look for the package:firefox job artifact (contains .xpi file).
- Safari: Look for the package:safari job artifact (contains aipage-safari.zip).

Chrome

Download aipage-chrome.zip (from the package:chrome job artifact).
Unzip the file to a folder on your computer.
Open Chrome and navigate to chrome://extensions/.
Enable "Developer mode" (toggle in the top-right corner).
Click "Load unpacked".
Select the unzipped folder.

Note on Manifest V2: Chrome has phased out Manifest V2 extensions. If you encounter issues loading the extension, please refer to this guide on how to enable Manifest V2 in Chrome.

If you are unable to enable Manifest V2 in Chrome, we recommend using Brave Browser, which retains support for Manifest V2 extensions.

Firefox

Download the .xpi file from the package:firefox job artifact.
Open Firefox and navigate to about:debugging#/runtime/this-firefox.
Click "Load Temporary Add-on".
Select the downloaded .xpi file.

Safari (macOS only)

Download aipage-safari.zip from the package:safari job artifact.
Unzip the file to get the application.
Run the application locally.
Open Safari Preferences → Extensions.
Enable the EduPage AI Sidebar extension.

Setting Up Your AI Provider

The extension supports multiple AI providers. Choose your preferred provider and configure the corresponding API key.

Supported Providers

Google Gemini (Default)
OpenAI ChatGPT
Anthropic Claude
Mistral AI
LM Studio (Local)
Ollama (Local)

Step 1: Choose Your Provider

Navigate to any EduPage site (e.g., https://yourschool.edupage.org)
Click the AI button (star icon) in the EduPage navbar
The sidebar will open showing the settings view
Select your preferred AI provider from the dropdown

Step 2: Configure Your Provider

Google Gemini

Visit Google AI Studio
Sign in with your Google account
Click "Get API Key" or "Create API Key"
Copy the key (starts with AIzaSy...)

Troubleshooting: If you encounter the error "We are unable to create an API key and a Google Cloud project for you", you may need to manually create a project in the Google Cloud Console first. See this forum post for more details.

OpenAI, Claude, Mistral

Follow the links in the sidebar settings to get your API keys from their respective consoles.

LM Studio (Local)

Open LM Studio and start the Local Inference Server.
Keep the default Port 1234 or update the Base URL in the extension settings.
Ensure a model is loaded in LM Studio.
Enter the Model Name if you want to target a specific one (default: loaded-model).

Ollama (Local)

Install Ollama and run it (ollama serve).
Download a model (e.g., ollama pull llama3).
Enter the Base URL (default: http://localhost:11434).
Enter the Model Name (e.g., llama3).

Step 3: Save Settings

Paste your API key into the "API Key" field
Click "Save Key"

Your API key is stored locally in your browser and is never sent anywhere except to your selected provider's API when you send messages.

Step 4: Start Chatting

Once your API key is saved:

The sidebar will automatically switch to the chat view
Type your question in the input field at the bottom
Press Enter or click the send button
The AI will respond to your queries

Switching Providers

You can switch between providers at any time:

Click the settings icon (gear) in the sidebar header
Select a different provider from the dropdown
Enter the API key for that provider (if not already saved)
Click "Save Key"

Each provider's API key is stored separately, so you can switch between them without re-entering keys.

Usage

Open/Close Sidebar: Click the AI button (star icon) in the EduPage navbar
Change Settings: Click the settings icon (gear) in the sidebar header
Send Messages: Type in the input field and press Enter or click send

Development

Project Structure

extension/
├── src/
│   ├── manifest.json           # Chrome manifest
│   ├── manifest.firefox.json   # Firefox manifest
│   ├── manifest.safari.json    # Safari manifest
│   ├── background.ts            # Background service worker
│   ├── content.ts               # Content script (injects sidebar)
│   ├── polyfills/
│   │   └── browser-polyfill.ts  # Cross-browser compatibility
│   └── sidebar/
│       ├── sidebar.html         # Sidebar UI
│       ├── sidebar.scss         # Sidebar styles
│       └── index.tsx            # Sidebar logic (React)
├── scripts/
│   └── setup-safari.sh          # Safari Xcode project generator
├── tests/
│   ├── sidebar.spec.ts          # Sidebar UI tests
│   ├── navbar.spec.ts           # Integration tests
│   ├── test-player.spec.ts      # Anti-cheat tests
│   └── context.spec.ts          # Context menu tests
├── dist-chrome/                 # Chrome build output
├── dist-firefox/                # Firefox build output
├── dist-safari/                 # Safari build output
└── build.ts                     # Multi-browser build script

Building

# Build for a specific browser
bun run build:chrome
bun run build:firefox
bun run build:safari

# Build for all browsers
bun run build:all

Running Tests

# Run all tests (builds Chrome first)
bun test

# Run specific test file
bunx playwright test tests/sidebar.spec.ts

# View test report
bunx playwright show-report

Packaging for Distribution

# Package Chrome extension (.zip)
bun run package:chrome

# Package Firefox extension (.xpi)
bun run package:firefox

# Outputs:
# - edupage-ai-sidebar-chrome.zip (for Chrome Web Store)
# - packages/*.xpi (for Firefox Add-ons)
# - Safari requires App Store submission via Xcode

CI/CD Pipeline

This project uses GitLab CI for automated building and testing:

Lint Stage: Runs ESLint on all TypeScript files
Build Stage: Builds extensions for Chrome, Firefox, and Safari in parallel
Test Stage: Runs Playwright tests on Chrome build
Package Stage: Creates distribution packages for all browsers

Troubleshooting

"Invalid API Key" Error

Verify your API key is correct
Ensure you copied the entire key (starts with AIzaSy)
Check that your API key hasn't been restricted or revoked in Google AI Studio

Ensure you're on an EduPage domain (*.edupage.org)
Check that the extension is enabled in chrome://extensions/
Try refreshing the page

Messages Not Sending

Verify your API key is saved (click settings icon to check)
Check your internet connection
Open browser console (F12) to see any error messages

Privacy & Security

Your API key is stored locally using Chrome's storage API
No data is sent to any server except the selected AI provider API
Conversations are not stored or logged by this extension

Anti-Cheat Protection

When a test is active (detected via .etest-player-header), the extension automatically:

Prevents Tab Switch Detection: Overrides the Visibility API (document.hidden, visibilityState) and blocks blur/focusout events.
Blocks Copy-Paste Detection: Prevents the site from detecting or blocking copy, cut, paste, and contextmenu actions.