Extension Setup Guide

The Periscope browser extension captures browsing activity and streams it to the Periscope service, where AI agents can access it. This guide walks through installation, sign-in, configuration, and verification.

Browser Support

Chromium-based browsers are preferred because the extension uses Manifest V3 APIs that have the best support on Chrome and Edge.

Installation

Chrome / Edge

1. Open the Lovelace Extensions page at extensions.uselovelace.com/periscope
2. Click Add to Chrome (or Add to Edge -- the Chrome Web Store works for both)
3. Confirm the permissions dialog
4. The Periscope icon appears in your browser toolbar

If the icon does not appear, click the puzzle piece icon in the toolbar and pin Periscope.

Firefox

1. Open the Lovelace Extensions page at extensions.uselovelace.com/periscope
2. Click Add to Firefox
3. Confirm the permissions dialog in the Firefox add-ons prompt
4. The Periscope icon appears in your toolbar

Manual Installation (Development)

For local development or testing unreleased builds:

# Clone the extension source
git clone https://github.com/ReasonableTech/periscope-extension.git
cd periscope-extension
pnpm install && pnpm build

Then load the unpacked extension:

• Chrome: Navigate to chrome://extensions, enable Developer Mode, click "Load unpacked", select the dist/ folder
• Firefox: Navigate to about:debugging#/runtime/this-firefox, click "Load Temporary Add-on", select dist/manifest.json

Sign-In Flow

The extension uses the Lovelace OAuth device flow for authentication. This avoids handling passwords in the extension and works across all supported browsers.

1. Click the Periscope icon in your toolbar
2. Click Sign In with Lovelace
3. A new tab opens to accounts.uselovelace.com/device with a pre-filled device code
4. Sign in to your Lovelace account (or create one if needed)
5. Approve the device authorization request
6. The extension tab updates to show "Connected" status
7. Close the authorization tab -- the extension is now authenticated

The extension stores a refresh token locally and renews the access token automatically. You should only need to sign in once per browser unless you explicitly sign out.

URL Pattern Rules

By default, the extension captures context from all HTTP and HTTPS pages. You can restrict this with URL pattern rules to control which sites are included or excluded.

Configuring Patterns

Open the extension popup and click Settings > URL Rules:

• Allow List mode: Only capture from URLs matching these patterns
• Block List mode: Capture from all URLs except those matching these patterns

Pattern syntax follows the Chrome match patterns format:

# Capture only from specific domains
https://github.com/*
https://docs.google.com/*
https://*.stackoverflow.com/*

# Block specific paths
https://mail.google.com/*
https://*.bank.com/*

Examples

Per-Domain Privacy Defaults

Each domain can have a default privacy level that controls how much context is shared with agents:

Setting Domain Defaults

1. Click the Periscope icon while on any page
2. Click the privacy level dropdown next to the domain name
3. Select the desired default level
4. The setting applies to all pages on that domain going forward

You can also configure domain defaults in bulk via Settings > Privacy > Domain Rules:

github.com         → public
stackoverflow.com  → public
mail.google.com    → restricted
mybank.com         → restricted
reddit.com         → filtered

Extension Permissions Explained

The extension requests these permissions during installation:

The extension does not request:

• history -- It does not read your browser history
• bookmarks -- It does not access your bookmarks
• downloads -- It does not interact with downloads
• cookies -- It does not read or write cookies

Verifying Sync Works

After installation and sign-in, verify that context is flowing correctly.

Check the Extension Popup

Click the Periscope icon. You should see:

• Connection status: "Connected" with a green indicator
• Current page: The title and URL of the active tab
• Last synced: A timestamp within the last few seconds

Verify via the REST API

Make a curl call to the Periscope API to confirm your browser context is reaching the service:

curl -s -H "Authorization: Bearer $LOVELACE_API_TOKEN" \
  https://periscope.uselovelace.com/api/v1/context/current | jq .

You should see a JSON response with your current tab's URL, title, and content (depending on privacy level):

{
  "id": "ctx_abc123",
  "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebSocket",
  "title": "WebSocket - Web APIs | MDN",
  "content": "The WebSocket interface provides...",
  "privacyLevel": "public",
  "timestamp": "2026-03-02T10:15:30.000Z",
  "device": {
    "name": "Chrome on MacBook",
    "os": "macOS",
    "formFactor": "desktop"
  }
}

Verify WebSocket Streaming

For real-time verification, use a quick WebSocket test:

# Using websocat (install with: brew install websocat)
echo '{"type":"auth","token":"YOUR_TOKEN"}' | \
  websocat wss://periscope.uselovelace.com/ws

# Then send a subscribe message
echo '{"type":"subscribe","channel":"current-context"}'

Navigate to a new page in your browser. You should see a context event appear in the WebSocket output.

Troubleshooting

Extension Shows "Disconnected"

1. Check your internet connection
2. Click the extension icon and click Reconnect
3. If the issue persists, sign out and sign back in
4. Check that periscope.uselovelace.com is not blocked by your network

No Context Appearing in API

1. Verify the extension shows "Connected" status
2. Check that the current page's domain is not set to restricted privacy
3. Check that the current page matches your URL pattern rules
4. Open the extension's Settings > Debug and check the event log for errors

Extension Not Capturing Content

1. Some pages block content extraction (e.g., pages with restrictive CSP headers)
2. PDF viewers and browser internal pages (chrome://, about:) cannot be captured
3. Pages loaded before the extension was installed need a refresh

High Memory Usage

The extension buffers content before sending it to the service. If you notice high memory usage:

1. Open Settings > Performance
2. Reduce the Content Buffer Size (default is 100KB per page)
3. Enable Lazy Content Capture to only capture content when the extension icon is clicked

Firefox-Specific Issues

• The extension may need to be re-enabled after Firefox updates
• Temporary add-on installations (for development) do not persist across browser restarts
• Content script injection timing may differ from Chromium -- report issues if context is missing on fast navigations