diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..78d23cf7e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Twenty is an open-source CRM built with modern technologies in a monorepo structure. The codebase is organized as an Nx workspace with multiple packages.
+
+## Key Commands
+
+### Development
+```bash
+# Start development environment (frontend + backend + worker)
+yarn start
+
+# Individual package development
+npx nx start twenty-front     # Start frontend dev server
+npx nx start twenty-server    # Start backend server
+npx nx run twenty-server:worker  # Start background worker
+```
+
+### Testing
+```bash
+# Run tests
+npx nx test twenty-front      # Frontend unit tests
+npx nx test twenty-server     # Backend unit tests
+npx nx run twenty-server:test:integration:with-db-reset  # Integration tests with DB reset
+
+# Storybook
+npx nx storybook:build twenty-front         # Build Storybook
+npx nx storybook:serve-and-test:static     # Run Storybook tests
+```
+
+### Code Quality
+```bash
+# Linting
+npx nx lint twenty-front      # Frontend linting
+npx nx lint twenty-server     # Backend linting
+npx nx lint twenty-front --fix  # Auto-fix linting issues
+
+# Type checking
+npx nx typecheck twenty-front
+npx nx typecheck twenty-server
+
+# Format code
+npx nx fmt twenty-front
+npx nx fmt twenty-server
+```
+
+### Build
+```bash
+# Build packages
+npx nx build twenty-front
+npx nx build twenty-server
+```
+
+### Database Operations
+```bash
+# Database management
+npx nx database:reset twenty-server         # Reset database
+npx nx run twenty-server:database:init:prod # Initialize database
+npx nx run twenty-server:database:migrate:prod # Run migrations
+
+# Generate migration
+npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/[name] -d src/database/typeorm/core/core.datasource.ts
+
+# Sync metadata
+npx nx run twenty-server:command workspace:sync-metadata -f
+```
+
+### GraphQL
+```bash
+# Generate GraphQL types
+npx nx run twenty-front:graphql:generate
+```
+
+## Architecture Overview
+
+### Tech Stack
+- **Frontend**: React 18, TypeScript, Recoil (state management), Emotion (styling), Vite
+- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)
+- **Monorepo**: Nx workspace managed with Yarn 4
+
+### Package Structure
+```
+packages/
+├── twenty-front/          # React frontend application
+├── twenty-server/         # NestJS backend API
+├── twenty-ui/             # Shared UI components library
+├── twenty-shared/         # Common types and utilities
+├── twenty-emails/         # Email templates with React Email
+├── twenty-chrome-extension/  # Chrome extension
+├── twenty-website/        # Next.js documentation website
+├── twenty-zapier/         # Zapier integration
+└── twenty-e2e-testing/    # Playwright E2E tests
+```
+
+### Key Development Principles
+- **Functional components only** (no class components)
+- **Named exports only** (no default exports)
+- **Types over interfaces** (except when extending third-party interfaces)
+- **String literals over enums** (except for GraphQL enums)
+- **No 'any' type allowed**
+- **Event handlers preferred over useEffect** for state updates
+
+### State Management
+- **Recoil** for global state management
+- Component-specific state with React hooks
+- GraphQL cache managed by Apollo Client
+
+### Backend Architecture
+- **NestJS modules** for feature organization
+- **TypeORM** for database ORM with PostgreSQL
+- **GraphQL** API with code-first approach
+- **Redis** for caching and session management
+- **BullMQ** for background job processing
+
+### Database
+- **PostgreSQL** as primary database
+- **Redis** for caching and sessions
+- **TypeORM migrations** for schema management
+- **ClickHouse** for analytics (when enabled)
+
+## Development Workflow
+
+### Before Making Changes
+1. Always run linting and type checking after code changes
+2. Test changes with relevant test suites
+3. Ensure database migrations are properly structured
+4. Check that GraphQL schema changes are backward compatible
+
+### Code Style Notes
+- Use **Emotion** for styling with styled-components pattern
+- Follow **Nx** workspace conventions for imports
+- Use **Lingui** for internationalization
+- Components should be in their own directories with tests and stories
+
+### Testing Strategy
+- **Unit tests** with Jest for both frontend and backend
+- **Integration tests** for critical backend workflows
+- **Storybook** for component development and testing
+- **E2E tests** with Playwright for critical user flows
+
+## Important Files
+- `nx.json` - Nx workspace configuration with task definitions
+- `tsconfig.base.json` - Base TypeScript configuration
+- `package.json` - Root package with workspace definitions
+- `.cursor/rules/` - Development guidelines and best practices
\ No newline at end of file