Introduction & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• extension/src/background/index.ts
• extension/src/content/index.ts
• backend/config/prompts.json
• extension/src/popup/index.html

Oddity 1 provides a browser-based annotation engine that uses AI to analyze essays, articles, research papers, and LLM chat transcripts. The system consists of a Chrome Extension (MV3), an Express API backend, and a shared library for type contracts and constants.

Sources: README.md:1-25, extension/src/content/index.ts:1-50

Project Architecture

The repository uses a monorepo structure with three primary workspaces. The extension interacts with the backend to generate AI annotations, which are then rendered as overlays and margin notes on the user's active tab.

The diagram shows the dependency flow between shared packages and the communication path between the extension and external AI/database services.

Sources: README.md:7-27, extension/src/background/index.ts:1-40

Component breakdown

Workspace	Component	Purpose
packages/shared	Types & Constants	Defines TypeScript contracts and shared values like BACKEND_URL.
extension	Service Worker	Manages auth, API client, message routing, and PDF detection.
extension	Content Script	Handles text extraction, DOM stability, and annotation rendering.
backend	Express API	Processes annotation requests, manages cache, and interacts with LLMs.

Sources: README.md:7-27, extension/src/content/index.ts:700-750

Local Development Setup

Setting up Oddity 1 requires installing root dependencies and configuring environment variables for both the backend and extension workspaces.

1. Initial Installation

Install all workspace dependencies from the root directory:

npm install

Sources: README.md:43-47

2. Backend Configuration

Create a backend/.env file with the following required secrets. The system uses Supabase for authentication and database management, and OpenRouter for AI inference.

Key	Description	Source
SUPABASE_URL	Supabase project endpoint	Supabase Dashboard
SUPABASE_ANON_KEY	Anonymous public key	Supabase Dashboard
OPENROUTER_API_KEY	API key for LLM access	openrouter.ai
OPENROUTER_MODEL	Default AI model identifier	openrouter.ai

Sources: README.md:30-40, README.md:52-64

3. Extension Configuration

Configure extension/.env to point to your local backend and Supabase instance.

VITE_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VITE_SUPABASE_ANON_KEY=<your anon key>
ODDITY_BACKEND_URL=http://localhost:3001
ODDITY_GOOGLE_OAUTH_CLIENT_ID=<your OAuth client id>

Sources: README.md:68-75

Execution & Deployment

The backend and extension must run concurrently for full functionality.

Running the System

1. Start Backend: Run npm run dev inside the backend/ directory. The server starts at http://localhost:3001.
2. Build Extension: Run npm run dev (watch mode) or npm run build in extension/.
3. Load in Chrome:
   • Navigate to chrome://extensions.
   • Enable Developer mode.
   • Click Load unpacked and select extension/dist/.

Sources: README.md:79-110

Execution Flow for Annotations

This sequence illustrates the lifecycle of an annotation request from initial page load to visual rendering.

Sources: extension/src/content/index.ts:900-1100, extension/src/background/index.ts:250-350, README.md:230-250

Authentication & Permissions

Oddity 1 uses Supabase Auth with Google OAuth. Users must sign in via the extension popup to enable annotation generation.

Extension Permissions

The manifest defines specific permissions required for system operation:

• activeTab: Reads URL and injects scripts.
• scripting: Programmatically injects scripts for PDF support.
• identity: Handles Google OAuth flow.
• host_permissions: <all_urls>: Allows injection on whitelisted sites.

Sources: README.md:118-132, extension/src/popup/index.html:430-480

Setup Requirements for AI

The file backend/config/prompts.json contains the system instructions for the LLM. You must replace placeholder values with real system prompts before the annotation feature functions correctly.

Sources: README.md:144-152, backend/config/prompts.json:1-50

Workflow & Development Standards

The project follows a specific orchestration logic for development tasks, primarily managed through CLAUDE.md.

• Plan Mode: Non-trivial tasks (3+ steps) require an explicit plan before implementation.
• Verification: Developers must run tests and verify logs before marking tasks complete.
• Simplicity: Changes should touch minimal code and prioritize root cause resolution over temporary fixes.

Sources: CLAUDE.md:1-60