diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000..681311e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7299e02
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Jupyter Server Documents is a JupyterLab extension that provides real-time collaboration (RTC) capabilities by moving document state to the server. The extension consists of:
+
+- **Python backend** (`jupyter_server_documents/`): Server extension handling WebSocket connections, room management, output processing, and collaboration state
+- **TypeScript frontend** (`src/`): JupyterLab extension providing UI components, document providers, and awareness indicators
+- **Hybrid architecture**: Frontend builds to `lib/` and gets packaged into `jupyter_server_documents/labextension/`
+
+## Development Commands
+
+### Setup
+
+```bash
+# Create development environment
+micromamba env create -f dev-environment.yml
+micromamba activate serverdocs
+
+# Development installation
+jlpm dev:install
+```
+
+### Building
+
+```bash
+# Build frontend only
+jlpm build
+
+# Build for production
+jlpm build:prod
+
+# Clean build artifacts
+jlpm clean:all
+```
+
+### Development Workflow
+
+```bash
+# Watch mode (auto-rebuild frontend on changes)
+jlpm watch
+
+# Start JupyterLab (in separate terminal)
+jupyter lab
+```
+
+### Testing
+
+```bash
+# Python tests
+pytest -vv -r ap --cov jupyter_server_documents
+
+# Frontend tests
+jlpm test
+
+# Integration tests (Playwright)
+cd ui-tests && yarn test
+```
+
+### Code Quality
+
+```bash
+# Lint and format
+jlpm lint
+
+# Check only (no fixes)
+jlpm lint:check
+```
+
+## Architecture
+
+### Backend Components
+
+- **`app.py`**: Main server extension (`ServerDocsApp`) - entry point and configuration
+- **`rooms/`**: Y-document room management and file-based collaboration state
+- **`outputs/`**: Notebook output processing and storage optimization
+- **`kernels/`**: Kernel management, execution state, and WebSocket connections
+- **`websockets/`**: WebSocket handlers for real-time collaboration
+- **`handlers.py`**: HTTP API endpoints
+
+### Frontend Components
+
+- **`src/docprovider/`**: Document providers, awareness, and Y.js integration
+- **`src/notebook-factory/`**: Custom notebook model and factory for collaboration
+- **`src/codemirror-binding/`**: CodeMirror editor bindings for real-time editing
+- **`src/executionindicator.tsx`**: UI component showing execution awareness
+
+### Key Patterns
+
+- Uses **Y.js/Yjs** for conflict-free replicated data types (CRDTs)
+- **WebSocket-based** real-time synchronization via `YRoomWebsocket`
+- **Output separation**: Large outputs stored separately from notebook documents
+- **Awareness protocol**: Shows user cursors and execution state across collaborators
+- **Kernel state management**: Handles kernel connections and execution across multiple users
+
+## Development Notes
+
+- After Python changes: restart Jupyter server
+- After frontend changes: run `jlpm build` and refresh browser
+- Frontend builds to `lib/` then packages to `jupyter_server_documents/labextension/`
+- Uses `jlpm` (JupyterLab's yarn) instead of npm/yarn directly
+- Development installation uses `uv` for faster Python package management