diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7c4b873
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+**Development**
+- `npm run dev` - Start development server with Vite (includes --host flag)
+- `npm run build` - Build for production (includes TypeScript check with vue-tsc -b)
+- `npm run preview` - Preview production build locally
+- `npm run analyze` - Build with bundle analysis (opens visualization)
+
+**Electron Development** 
+- `npm run electron:dev` - Run both Vite dev server and Electron concurrently
+- `npm run electron:build` - Full build and package for Electron
+- `npm run start` - Start Electron using Forge
+- `npm run package` - Package Electron app with Forge
+- `npm run make` - Create distributables with Electron Forge
+
+## Architecture Overview
+
+This is a Vue 3 + TypeScript + Vite application with Electron support, featuring a Nostr protocol client and Lightning Network integration for events/ticketing.
+
+**Core Stack:**
+- Vue 3 with Composition API (`<script setup>` style)
+- TypeScript throughout
+- Vite build system with PWA support
+- Electron for desktop app packaging
+- Pinia for state management
+- Vue Router for navigation
+- TailwindCSS v4 with Shadcn/ui components
+- Vue-i18n for internationalization
+
+**Key Features:**
+- Nostr protocol client for decentralized social networking
+- Lightning Network integration for event ticketing
+- PWA capabilities with service worker
+- Theme switching and language switching
+- Real-time connection status monitoring
+
+**Directory Structure:**
+- `src/components/` - Vue components organized by feature
+  - `ui/` - Shadcn/ui component library
+  - `nostr/` - Nostr-specific components
+  - `events/` - Event/ticketing components
+  - `layout/` - App layout components
+- `src/composables/` - Vue composables for reusable logic
+- `src/stores/` - Pinia stores for state management
+- `src/lib/` - Core business logic
+  - `nostr/` - Nostr client implementation
+  - `api/` - API integrations
+  - `types/` - TypeScript type definitions
+- `src/pages/` - Route pages
+- `electron/` - Electron main process code
+
+**Nostr Integration:**
+The app connects to Nostr relays using a custom NostrClient class built on nostr-tools. Key files:
+- `src/lib/nostr/client.ts` - Core Nostr client implementation
+- `src/composables/useNostr.ts` - Vue composable for Nostr connection management
+- `src/stores/nostr.ts` - Pinia store for Nostr state
+
+**Code Conventions:**
+- Use TypeScript interfaces over types for extendability
+- Prefer functional and declarative patterns over classes
+- Use Vue Composition API with `<script setup>` syntax
+- Follow naming convention: lowercase-with-dashes for directories
+- Leverage VueUse functions for enhanced reactivity
+- Implement lazy loading for non-critical components
+- Optimize images using WebP format with lazy loading
+
+**Build Configuration:**
+- Vite config includes PWA, image optimization, and bundle analysis
+- Manual chunking strategy for vendor libraries (vue-vendor, ui-vendor, shadcn)
+- Electron Forge configured for cross-platform packaging
+- TailwindCSS v4 integration via Vite plugin
+
+**Environment:**
+- Nostr relay configuration via `VITE_NOSTR_RELAYS` environment variable
+- PWA manifest configured for standalone app experience
+- Service worker with automatic updates every hour
\ No newline at end of file