diff --git a/server/CLAUDE.md b/server/CLAUDE.md
new file mode 100644
index 0000000..d115880
--- /dev/null
+++ b/server/CLAUDE.md
@@ -0,0 +1,88 @@
+# Claude Instructions for WLED Screen Controller Server
+
+## Development Workflow
+
+### Server Restart Policy
+
+**IMPORTANT**: When making changes to server code (Python files in `src/wled_controller/`), you MUST restart the server if it's currently running to ensure the changes take effect.
+
+#### When to restart:
+- After modifying API routes (`api/routes.py`, `api/schemas.py`)
+- After updating core logic (`core/*.py`)
+- After changing configuration (`config.py`)
+- After modifying utilities (`utils/*.py`)
+- After updating data models or database schemas
+
+#### How to check if server is running:
+```bash
+# Look for running Python processes with wled_controller
+ps aux | grep wled_controller
+# Or check for processes listening on port 8080
+netstat -an | grep 8080
+```
+
+#### How to restart:
+1. Stop the current server (if running as background task, use TaskStop with the task ID)
+2. Start a new server instance:
+   ```bash
+   cd server && python -m wled_controller.main
+   ```
+3. Verify the new server started successfully by checking the output logs
+
+#### Files that DON'T require restart:
+- Static files (`static/*.html`, `static/*.css`, `static/*.js`) - these are served directly
+- Locale files (`static/locales/*.json`) - loaded by frontend
+- Documentation files (`*.md`)
+- Configuration files in `config/` if server supports hot-reload (check implementation)
+
+### Testing Changes
+
+After restarting the server with new code:
+1. Test the modified endpoints/functionality
+2. Check browser console for any JavaScript errors
+3. Verify API responses match updated schemas
+4. Test with different locales if i18n was modified
+
+## Project Structure Notes
+
+- `src/wled_controller/main.py` - FastAPI application entry point
+- `src/wled_controller/api/` - REST API endpoints and schemas
+- `src/wled_controller/core/` - Core business logic (screen capture, WLED client, processing)
+- `src/wled_controller/utils/` - Utility functions (logging, monitor detection)
+- `src/wled_controller/static/` - Frontend files (HTML, CSS, JS, locales)
+- `config/` - Configuration files (YAML)
+- `data/` - Runtime data (devices.json, persistence)
+
+## Common Tasks
+
+### Adding a new API endpoint:
+1. Add route to `api/routes.py`
+2. Define request/response schemas in `api/schemas.py`
+3. **Restart the server**
+4. Test the endpoint via `/docs` (Swagger UI)
+
+### Adding a new field to existing API:
+1. Update Pydantic schema in `api/schemas.py`
+2. Update corresponding dataclass (if applicable)
+3. Update backend logic to populate the field
+4. **Restart the server**
+5. Update frontend to display the new field
+
+### Modifying display/monitor detection:
+1. Update functions in `utils/monitor_names.py` or `core/screen_capture.py`
+2. **Restart the server**
+3. Test with `GET /api/v1/config/displays`
+
+### Adding translations:
+1. Add keys to `static/locales/en.json` and `static/locales/ru.json`
+2. Add `data-i18n` attributes to HTML elements in `static/index.html`
+3. Use `t('key')` function in `static/app.js` for dynamic content
+4. No server restart needed (frontend only)
+
+## Authentication
+
+Server uses API key authentication. Keys are configured in:
+- `config/default_config.yaml` under `auth.api_keys`
+- Or via environment variables: `WLED_AUTH__API_KEYS`
+
+For development, ensure at least one API key is configured or the server won't start.