diff --git a/.gitignore b/.gitignore
index 8612f7e..5a5deec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ node_modules
 .vscode/*
 !.vscode/*.shared.json
 !.vscode/extensions.json
+.claude
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8d4f699
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is @justbe/webview, a cross-platform library for building web-based desktop apps. The architecture consists of:
+
+- **Rust backend**: Core webview functionality using `tao` and `wry`
+- **Multi-language clients**: Deno/TypeScript and Python clients that interface with the Rust binary via stdio
+
+## Essential Commands
+
+### Build Commands
+```bash
+# Build everything
+mise build
+
+# Build specific targets
+mise build:rust    # Build the webview binary
+mise build:deno    # Build Deno client
+mise build:python  # Build Python client
+```
+
+### Code Generation
+```bash
+# Generate all schemas and clients
+mise gen
+
+# Generate specific parts
+mise gen:rust    # Generate JSON schemas from Rust
+mise gen:deno    # Generate TypeScript client
+mise gen:python  # Generate Python client
+```
+
+### Linting and Type Checking
+```bash
+# Run all lints
+mise lint
+
+# Specific lints
+mise lint:rust     # cargo fmt --check && cargo clippy
+mise lint:deno     # deno lint && deno check
+mise lint:ast-grep # AST-based linting
+```
+
+### Running Examples
+```bash
+# Run Deno example
+mise example:deno example=basic
+
+# Run Python example  
+mise example:python example=basic
+```
+
+### Version Management
+```bash
+# Sync version numbers across all packages
+mise sync-versions
+```
+
+## Architecture
+
+### IPC Communication
+- Client libraries communicate with the Rust binary via stdio (standard input/output)
+- Messages are JSON-encoded and follow schemas defined in `schemas/`
+- Schema-driven development ensures type safety across language boundaries
+
+### Directory Structure
+- `src/` - Rust source code
+- `src/clients/deno/` - Deno/TypeScript client
+- `src/clients/python/` - Python client  
+- `schemas/` - JSON schemas for IPC messages
+- `scripts/` - Build and generation scripts
+- `sg/` - AST-grep linting rules
+
+### Key Files
+- `mise.toml` - Task runner configuration and tool versions
+- `Cargo.toml` - Rust dependencies and build settings
+- `src/clients/deno/deno.json` - Deno project configuration
+- `src/clients/python/pyproject.toml` - Python project configuration
+
+### Development Workflow
+1. Rust structs define the message protocol
+2. `mise gen:rust` generates JSON schemas from Rust code
+3. `mise gen:deno` and `mise gen:python` generate typed clients from schemas
+4. Clients automatically download platform binaries if needed
+5. Communication happens via JSON messages over stdio
\ No newline at end of file