diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5711af1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an IntelliJ IDEA plugin that provides Slint language support through LSP (Language Server Protocol) integration. The plugin downloads platform-specific Slint LSP binaries from GitHub releases and integrates them with IntelliJ's LSP infrastructure.
+
+## Build System
+
+This project uses Gradle with the Kotlin DSL and the IntelliJ Platform Gradle Plugin.
+
+### Common Commands
+
+**Build the plugin:**
+```bash
+./gradlew build
+```
+
+**Run the plugin in a sandbox IDE:**
+```bash
+./gradlew runIde
+```
+
+**Run tests:**
+```bash
+./gradlew test
+```
+
+**Verify plugin compatibility:**
+```bash
+./gradlew verifyPlugin
+```
+
+**Build plugin distribution ZIP:**
+```bash
+./gradlew buildPlugin
+```
+
+**Clean build artifacts:**
+```bash
+./gradlew clean
+```
+
+## Architecture
+
+### LSP Integration
+
+The plugin uses IntelliJ's LSP support (`com.intellij.modules.lsp`) to provide language features for `.slint` files.
+
+**Key components:**
+
+- `SlintLspServerSupportProvider` (src/main/kotlin/me/zhouxi/slint/lsp/SlintLspServerSupportProvider.kt:13): Main LSP integration point. Implements `LspServerSupportProvider` to start the Slint LSP server when `.slint` files are opened.
+
+- `SlintRuntime` (src/main/kotlin/me/zhouxi/slint/SlintRuntime.kt:8): Manages plugin paths and locates the platform-specific LSP binary. Detects OS (Windows/Linux/macOS) and resolves the correct executable path.
+
+- `FooLspServerDescriptor` (src/main/kotlin/me/zhouxi/slint/lsp/SlintLspServerSupportProvider.kt:34): Internal descriptor that creates the command line for launching the LSP server.
+
+### Binary Distribution
+
+The build process downloads platform-specific Slint LSP binaries from GitHub releases:
+
+- **Download task** (build.gradle.kts:72-79): Downloads LSP binaries for Linux, macOS, and Windows from `https://github.com/slint-ui/slint/releases/download/v{version}/`
+
+- **Extract task** (build.gradle.kts:80-104): Extracts and renames binaries to standardized names (`slint-lsp-linux`, `slint-lsp-macos`, `slint-lsp-windows.exe`)
+
+- **Sandbox preparation** (build.gradle.kts:105-111): Copies extracted binaries to `slint/lsp/` directory in the plugin sandbox
+
+The Slint version is configured in `gradle.properties` via the `slintVersion` property.
+
+### Plugin Configuration
+
+- **plugin.xml** (src/main/resources/META-INF/plugin.xml): Declares the plugin metadata, dependencies, and extension points. Registers `SlintLspServerSupportProvider` as the LSP server support provider.
+
+- **Target IDE version**: IntelliJ IDEA 2025.2.4 with minimum build 252.25557 (configured in build.gradle.kts:43,56)
+
+- **Java/Kotlin version**: JVM 21 (build.gradle.kts:68-70,114-118)
+
+## Project Structure
+
+```
+src/main/kotlin/me/zhouxi/slint/
+├── SlintRuntime.kt              # Plugin runtime and binary path resolution
+├── icons/SlintIcons.kt          # Icon resources for UI
+└── lsp/
+    └── SlintLspServerSupportProvider.kt  # LSP integration
+```
+
+## Testing the Plugin
+
+### Manual Testing
+
+1. **Build and run in sandbox:**
+   ```bash
+   ./gradlew runIde
+   ```
+
+2. **Test with sample file:**
+   - Open `test-files/hello.slint`
+   - Verify file icon, syntax highlighting, and LSP features
+
+3. **Test LSP features:**
+   - Code completion: Type and press Ctrl+Space
+   - Goto definition: Ctrl+Click on symbols
+   - Hover: Mouse over symbols
+   - Diagnostics: Introduce syntax errors
+   - Formatting: Ctrl+Alt+L
+
+### Verify LSP Server
+
+Check LSP server status in the status bar (bottom right). Should show "Slint" when a .slint file is open.
+
+### Common Issues
+
+- **LSP server not starting**: Check that LSP binary exists in sandbox at `sandbox/plugins/slint/lsp/slint-lsp-{platform}`
+- **No syntax highlighting**: Verify TextMate grammar file is in resources
+- **No completion**: Check LSP server logs in `idea.log`
+
+## Development Notes
+
+- The plugin uses IntelliJ's built-in LSP client infrastructure, so language features (completion, diagnostics, etc.) are provided by the Slint LSP server itself.
+
+- The sandbox directory is configured to `sandbox/` in the project root (build.gradle.kts:53).
+
+- When modifying LSP integration, test by running `./gradlew runIde` which launches a sandbox IDE with the plugin installed.
+
+- To update the Slint LSP version, change `slintVersion` in `gradle.properties` and rebuild. The build will download new binaries automatically.