diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6d746b5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MSR Mod is a browser extension that provides an alternate frontend for Monster Siren Records (monster-siren.hypergryph.com). It's built with Vue 3, TypeScript, and Tailwind CSS, designed to work as both Chrome and Firefox extensions.
+
+## Common Commands
+
+### Development
+```bash
+npm run dev                 # Start development server with Vite
+npm run dev:refresh         # Build and refresh dist folder for extension development
+npm i                       # Install dependencies
+```
+
+### Building
+```bash
+npm run build:chrome        # Build for Chrome/Chromium browsers
+npm run build:firefox       # Build for Firefox
+npm run build              # Default build (Chrome)
+```
+
+### Code Quality
+```bash
+npm run lint               # Format code with Biome
+npm run quality-check      # Run Biome CI checks
+npm run qc                 # Alias for quality-check
+```
+
+### Extension Development Workflow
+1. Run `npm run dev:refresh` to build initial dist folder
+2. Load the `dist` folder as an unpacked extension in browser
+3. Use `npm run dev` for hot-reload development
+4. Use `npm run build:watch` for continuous builds
+
+## Architecture
+
+### Core Technologies
+- **Vue 3** with Composition API and `<script setup>` syntax
+- **TypeScript** for type safety
+- **Pinia** for state management
+- **Vue Router** with hash history for extension compatibility
+- **Tailwind CSS v4** for styling
+- **GSAP** for animations
+- **Axios** for API communication
+
+### Browser Extension Structure
+- **Manifest V3** with platform-specific builds
+- **Content Scripts** inject the frontend on monster-siren.hypergryph.com
+- **Background Service Worker** handles extension lifecycle
+- **Cross-platform compatibility** via prebuild scripts
+
+### State Management (Pinia Stores)
+- **usePlayQueueStore**: Music playback queue, shuffle/repeat modes, audio preloading
+- **useFavourites**: User favorites with cross-platform storage (Chrome storage API/localStorage)
+- **usePreferences**: User settings and preferences
+
+### Key Components
+- **Player**: Main audio player with preloading and resource validation
+- **Playroom**: Full-screen player interface with lyrics and visualizations
+- **ScrollingLyrics**: Animated lyrics display with auto-scroll and user interaction
+- **PlayListItem/TrackItem**: Reusable music track components
+
+### API Integration
+- **Monster Siren API**: Fetches songs, albums, and metadata via `src/apis/index.ts`
+- **Resource URL Validation**: Automatic refresh of cached URLs when servers rotate resources
+- **Preloading System**: Smart audio preloading with cache management
+
+### Browser Compatibility
+- **Chrome**: Uses service worker, full CSP support
+- **Firefox**: Uses background scripts, modified CSP, specific gecko settings
+- **Prebuild Scripts**: Automatically modify manifest.json and HTML for each platform
+
+### Storage Strategy
+- **Favorites**: Stored in Chrome storage API (fallback to localStorage)
+- **Preferences**: Browser-specific storage with graceful degradation
+- **Audio Cache**: In-memory preloading with size limits
+
+### Resource Management
+- **Audio Preloading**: Validates and preloads next track during playback
+- **URL Refresh Logic**: Checks resource availability before playback/preload
+- **Cache Invalidation**: Automatic cleanup when resource URLs change
+
+## File Structure Notes
+
+### `/src/utils/`
+- **songResourceChecker.ts**: Centralized resource validation and refresh logic
+- **audioVisualizer.ts**: Real-time audio analysis for visual effects
+- **artistsOrganize.ts**: Helper for formatting artist names
+
+### `/scripts/`
+- **prebuild-chrome.js**: Removes localhost dev configs for production
+- **prebuild-firefox.js**: Adapts manifest for Firefox compatibility
+
+### `/public/`
+- **manifest.json**: Extension manifest (modified by prebuild scripts)
+- **content.js**: Injects the Vue app into target websites
+- **background.js**: Extension background script
+
+## Development Considerations
+
+### Extension Context
+- Uses hash routing for browser extension compatibility
+- CSP restrictions require specific script and style handling
+- Cross-origin requests limited to declared host permissions
+
+### Performance
+- Audio preloading system prevents playback interruptions
+- Resource validation happens only when needed (playback/preload)
+- GSAP animations with proper cleanup to prevent memory leaks
+
+### Error Handling
+- Graceful fallbacks for storage API unavailability
+- Resource URL rotation handling with automatic refresh
+- Cross-browser compatibility with feature detection
\ No newline at end of file