diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..290277c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+"掐日子" (Qia Rizi) - A Chinese calendar reminder app with anniversaries, reminders, and notes. Built with React 19 + TypeScript + Supabase.
+
+## Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start dev server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run linting
+pnpm lint
+
+# Preview production build
+pnpm preview
+```
+
+## Architecture
+
+### Frontend (client/)
+- **React 19 + TypeScript + Vite** - Core framework
+- **Mantine UI v8** - Component library with custom Apple-inspired theme
+- **Zustand** - State management with localStorage persistence
+- **React Router v7** - Routing
+- **Supabase** - Backend (auth, database)
+
+### Key Directories
+- `src/pages/` - Route pages (HomePage, LoginPage, RegisterPage, SettingsPage, ArchivePage)
+- `src/components/` - Reusable components, organized by feature
+- `src/stores/` - Zustand store (useAppStore for global state)
+- `src/services/` - API layer (supabase.ts, api.ts)
+- `src/types/` - TypeScript type definitions
+- `src/utils/` - Business logic utilities (repeatCalculator, countdown)
+
+### Data Model
+- **Events**: Anniversary/Reminder items with repeat rules, lunar calendar support
+- **Notes**: User's personal notes (HTML content)
+- **AI Conversations**: Chat history with AI event parsing
+
+## Key Patterns
+
+### State Management
+- Use `useAppStore` from `src/stores/index.ts` for global state (auth, events, notes)
+- Store persists to localStorage via zustand/middleware
+
+### API Calls
+- Direct Supabase calls via `services/supabase.ts`
+- Auth token handling with automatic refresh in store's `checkAuth`
+
+### Components
+- Custom date/time pickers in `src/components/common/` (FixedCalendar, WheelTimePicker)
+- Event cards use context menus from `src/stores/contextMenu.ts`
+
+## Chinese Localization
+- App uses Simplified Chinese (zh-cn) throughout
+- dayjs configured with Chinese locale
+- Mantine DatesProvider set to Chinese