Browser Extension (WXT)
Relevant source files
The following files were used as context for generating this wiki page:
The tldw Assistant is a cross-browser extension built using the WXT framework, serving as the primary browser-integrated frontend for the tldw_server. It enables users to interact with AI models, perform RAG (retrieval-augmented generation) searches, and process web media directly from their browser environment. The extension supports Chrome, Firefox, Edge, and other Chromium-based browsers like Brave and Vivaldi.
Architecturally, the extension is part of a monorepo workspace. It shares a significant portion of its UI logic, components, and services with the Next.js Web UI, while utilizing thin entry wrappers and WXT-specific configurations to handle extension-specific lifecycles and APIs.
Sources: apps/extension/README.md:10-18, apps/extension/AGENTS.md:7-14, apps/extension/CLAUDE.md:7-14
System Architecture
The extension follows a modular monorepo structure where the core business logic resides in packages/ui/src/, and the apps/extension/ directory handles the build configuration and entry point definitions.
The diagram above illustrates the monorepo architecture where both the Extension and Web UI consume shared resources from the UI package.
Sources: apps/extension/AGENTS.md:31-50, apps/DEVELOPMENT.md:38-66
Core Components and Entry Points
The extension is organized into several distinct execution contexts defined by the WXT framework:
| Entry Point | Location | Description |
|---|---|---|
| Background Script | src/entries/background.ts | A service worker handling daemon-like tasks: context menus, keyboard shortcuts, and message passing. |
| Sidepanel | src/entries/sidepanel/ | The primary chat interface that slides into the browser window. |
| Options Page | src/entries/options/ | A full-tab settings UI for server configuration and specialized tools like repo2txt. |
| Content Scripts | src/entries/*.content.ts | Scripts injected into web pages to interact with DOM content (e.g., selection scraping). |
Sources: apps/extension/AGENTS.md:65-82, apps/extension/README.md:120-130
Data Flow and Communication
Communication between the extension components and the tldw_server backend is mediated through a typed messaging protocol and background proxies.
This flow ensures that sensitive authentication credentials (like API keys) are managed in the background context rather than being exposed directly in the UI layer.
Sources: apps/extension/AGENTS.md:213-241, apps/extension/README.md:144-155
Messaging Protocol Patterns
The extension uses a strictly typed message protocol for Inter-Process Communication (IPC). This includes:
- Typed Message Protocol: Discriminated unions for message types (e.g.,
tldw:request,tldw:models:refresh). - Response Envelopes: Consistent objects containing
ok,data,error, andstatusfields. - Background Proxies: Helpers like
bgRequest,bgStream, andbgUploadfacilitate secure API calls.
Sources: apps/extension/AGENTS.md:213-241, apps/extension/README.md:150-155
Build System and Branch Awareness
The extension uses a custom build process that is branch-aware. This ensures that the production environment (main branch) and development environments (feature branches) produce distinct artifacts.
The "Branch-Aware" design prevents developers from accidentally distributing development builds as release-ready artifacts.
Sources: Docs/superpowers/specs/2026-04-10-branch-aware-webui-extension-artifact-profiles-design.md:13-35, apps/extension/README.md:58-85
Common Build Commands
| Command | Browser | Environment |
|---|---|---|
bun dev | Chrome | Development (Hot Reload) |
bun run build | All | Branch-determined |
bun run build:chrome:prod | Chrome | Forced Production |
bun run zip:dev | Chrome | Forced Dev Archive |
Sources: apps/extension/README.md:51-78, apps/extension/AGENTS.md:88-112
Storage and State Management
The extension utilizes two primary layers for persisting data:
- Zustand (State Management): Used for volatile and persisted UI state (e.g.,
model.tsx,option.tsx). - Dexie / IndexedDB (Database Layer): Used for heavy relational data.
models.ts: Storage for AI model configurations.knowledge.ts: RAG knowledge base.vector.ts: Vector embeddings for retrieval.
Sources: apps/extension/AGENTS.md:76-88, apps/extension/CLAUDE.md:76-88
Security Implementation
Security is integrated into the build and runtime phases:
- XSS Protection: A
safeInnerHTMLPlugininwxt.config.tsautomatically wraps allinnerHTMLassignments with DOMPurify at build time. - Content Security Policy (CSP): Production builds strictly disallow
unsafe-evalandunsafe-inline. - Auth Header Protection: Background proxies strip pre-existing Authorization headers to prevent injection attacks before adding valid extension-managed credentials.
Sources: apps/extension/AGENTS.md:275-295, apps/extension/CLAUDE.md:275-295
Summary
The tldw Assistant browser extension provides a robust, secure, and cross-browser interface for AI-powered research. By leveraging the WXT framework and a shared monorepo architecture, it maintains feature parity with the project's Web UI while providing deep browser integration through sidepanels, context menus, and background processing. Its branch-aware build system and strictly typed messaging ensure reliable development and production lifecycles.