diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..fe1db22
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,181 @@
+# Contributing to llmpane
+
+Thank you for your interest in contributing to llmpane! This guide will help you get started with development.
+
+## Project Structure
+
+llmpane is a monorepo containing:
+
+```
+llmpane/
+├── packages/
+│   ├── llmpane-py/        # Python package (Pydantic models, FastAPI utilities)
+│   └── llmpane-react/     # React package (UI components, hooks)
+└── examples/
+    └── fastapi-example/   # Complete working demonstration app
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Node.js 18+
+- npm 9+
+
+## Development Setup
+
+### Python Package
+
+```bash
+cd packages/llmpane-py
+
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install with development dependencies
+pip install -e ".[all]"
+```
+
+### React Package
+
+```bash
+cd packages/llmpane-react
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Or run in watch mode for development
+npm run dev
+```
+
+### Example Application
+
+The example app is useful for testing changes to both packages:
+
+```bash
+# Terminal 1: Start the backend
+cd examples/fastapi-example
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+python main.py
+
+# Terminal 2: Start the frontend
+cd examples/fastapi-example/frontend
+npm install
+npm run dev
+```
+
+The frontend will be available at `http://localhost:5173` and the backend at `http://localhost:8000`.
+
+You can customize ports using environment variables:
+
+```bash
+# Backend
+PORT=8001 python main.py
+
+# Frontend (must match backend port)
+BACKEND_PORT=8001 npm run dev
+```
+
+## Running Tests
+
+### Python Tests
+
+```bash
+cd packages/llmpane-py
+pytest -v
+```
+
+### React Tests
+
+```bash
+cd packages/llmpane-react
+npm run test:run
+```
+
+## Code Quality
+
+### Python
+
+We use [Ruff](https://github.com/astral-sh/ruff) for linting and [mypy](https://mypy-lang.org/) for type checking:
+
+```bash
+cd packages/llmpane-py
+
+# Linting
+ruff check llmpane
+
+# Type checking
+mypy llmpane
+```
+
+### React/TypeScript
+
+We use ESLint for linting:
+
+```bash
+cd packages/llmpane-react
+npm run lint
+```
+
+## Code Style Guidelines
+
+### Python
+
+- Use Pydantic models over dicts and tuples
+- Prefer early returns over deeply nested conditionals
+- Use `match/case` over `elif` chains
+- Use modern Python 3.10+ typing syntax
+- Write descriptive names: classes are nouns (`ChatMessage`), functions are verbs (`process_message()`)
+
+### TypeScript
+
+- Use TypeScript strict mode
+- Define proper types for all props and state
+- Prefer functional components with hooks
+
+## Making Changes
+
+1. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** and ensure:
+   - All tests pass
+   - Linting passes
+   - Type checking passes
+   - New features have tests
+
+3. **Commit your changes** with a clear message:
+   ```bash
+   git commit -m "Add feature description"
+   ```
+
+4. **Push and create a pull request** against `main`
+
+## Testing Your Changes
+
+Before submitting a PR, run the full test suite:
+
+```bash
+# Python
+cd packages/llmpane-py
+pytest -v
+ruff check llmpane
+mypy llmpane
+
+# React
+cd packages/llmpane-react
+npm run test:run
+npm run lint
+npm run build
+```
+
+## Questions?
+
+If you have questions or need help, feel free to open an issue on GitHub.