diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..f0075cf4e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+evcc is an extensible EV Charge Controller and home energy management system written in Go with a Vue.js frontend. It manages electric vehicle charging, integrates with solar systems, and provides local energy management without cloud dependencies.
+
+## Core Development Commands
+
+### Build & Development
+
+- `make` - Build the full application (UI + Go binary)
+- `make build` - Build Go binary only
+- `make ui` - Build UI assets only
+- `go run ./...` - Run without building binary
+- `./evcc` - Run the built binary
+- `./evcc --demo` - Run with demo configuration
+
+### Dependencies
+
+- `make install` - Install Go tools and dependencies
+- `make install-ui` - Install Node.js dependencies (`npm ci`)
+
+### Testing & Quality
+
+- `make test` - Run Go tests
+- `make test-ui` - Run frontend tests (`npm test`)
+- `make lint` - Run Go linting (golangci-lint)
+- `make lint-ui` - Run frontend linting (Prettier, ESLint, TypeScript)
+
+### Frontend Development
+
+- `npm run dev` - Start Vue dev server (http://127.0.0.1:7071)
+- `npm run storybook` - Run Storybook (http://127.0.0.1:6006)
+- `npm run playwright` - Run integration tests
+- `npm run simulator` - Run device simulator (http://localhost:7072)
+
+### Device Templates
+
+- `evcc --template-type charger --template new-charger-template.yaml` - Test device templates
+- `make docs` - Generate template documentation
+
+## Architecture
+
+### Core Components
+
+- **main.go** - Entry point, embeds web assets and i18n files
+- **cmd/** - CLI commands and application setup
+- **core/** - Core business logic:
+  - **loadpoint.go** - EV charging point management
+  - **site.go** - Site-wide energy management
+  - **planner/** - Smart charging planning
+  - **coordinator/** - Multi-loadpoint coordination
+- **api/** - API definitions and types
+- **server/** - HTTP server, WebSocket, MQTT, and database
+- **charger/**, **meter/**, **vehicle/** - Device integrations
+- **tariff/** - Tariff integrations
+- **plugin/** - Plugin system for device and tariff communication
+- **assets/** - Vue.js frontend application
+
+### Frontend Structure
+
+- **assets/js/** - TypeScript/Vue.js application
+- **assets/views/** - Vue components and pages
+- **i18n/** - Internationalization files
+- **dist/** - Built frontend assets (generated)
+
+### Configuration
+
+- Uses YAML configuration files
+- Templates in `templates/definition/` for device and tariff configurations
+- Database: SQLite (default: `evcc.db`)
+
+## Key Development Patterns
+
+### Device Integration
+
+- Device types: chargers, meters, vehicles (and tariffs)
+- Plugin system supports: Modbus, HTTP, MQTT, JavaScript, Go
+- Templates define device capabilities and configuration
+- Use `_blueprint.go` as starting point for new Go implementations
+
+### Testing
+
+- Go tests use standard `testing` package
+- Frontend tests use Vitest
+- Integration tests use Playwright
+- Simulator available for testing without real devices
+
+### Internationalization
+
+- Translations managed via Weblate
+- Update both `i18n/de.json` and `i18n/en.json` for new strings
+- Use `$t()` function in Vue components
+
+## Important File Locations
+
+- Configuration: `evcc.yaml` (or specified with `--config`)
+- Database: `evcc.db` (or specified with `--database`)
+- Device templates: `templates/definition/`
+- Web assets: `assets/` (source), `dist/` (built)
+- Generated code: Files ending in `_enumer.go`, `*_decorators.go`
+
+## Common Development Workflows
+
+### Adding New Device Support
+
+1. Create template in `templates/definition/[type]/`
+2. If Go code needed, implement in respective package
+3. Test with `evcc --template-type [type] --template [file]`
+4. Run `make docs` to update documentation
+
+### Frontend Development
+
+1. Start backend: `make build && ./evcc`
+2. Start frontend dev server: `npm run dev`
+3. Access development UI at http://127.0.0.1:7071
+
+### Integration Testing
+
+1. Build application: `make ui build`
+2. Run tests: `npm run playwright`
+3. Use simulator for device testing: `npm run simulator`