diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c6f7d72
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,111 @@
+# Lux Project Notes
+
+## Development Environment
+
+This is a **Nix environment**. Tools like `cargo`, `rustc`, `clippy`, etc. are not available in the base shell.
+
+To run Rust/Cargo commands, use one of:
+```bash
+nix develop --command cargo test
+nix develop --command cargo build
+nix develop --command cargo clippy
+nix develop --command cargo fmt
+```
+
+Or enter the development shell first:
+```bash
+nix develop
+# then run commands normally
+cargo test
+```
+
+The `lux` binary can be run directly if already built:
+```bash
+./target/debug/lux test
+./target/release/lux <file.lux>
+```
+
+For additional tools not in the dev shell:
+```bash
+nix-shell -p <program>
+```
+
+## Development Workflow
+
+When making changes:
+1. **Always run tests**: `cargo check && cargo test` - fix all errors and warnings
+2. **Lint the Lux code**: `./target/release/lux lint` - fix warnings
+3. **Check Lux code**: `./target/release/lux check` - type check + lint in one pass
+4. **Format Lux code**: `./target/release/lux fmt` - auto-format all .lux files
+5. **Write tests**: Add tests to cover new code
+6. **Document features**: Provide documentation and tutorials for new features/frameworks
+7. **Fix language limitations**: If you encounter parser/type system limitations, fix them (without regressions on guarantees or speed)
+8. **Git commits**: Always use `--no-gpg-sign` flag
+
+### Post-work checklist (run after each major piece of work)
+```bash
+nix develop --command cargo check       # No Rust errors
+nix develop --command cargo test        # All tests pass (currently 381)
+./target/release/lux check              # Type check + lint all .lux files
+./target/release/lux fmt                # Format all .lux files
+./target/release/lux lint               # Standalone lint pass
+```
+
+**IMPORTANT: Always verify Lux code you write:**
+- Run with interpreter: `./target/release/lux file.lux`
+- Compile to binary: `./target/release/lux compile file.lux`
+- Both must work before claiming code is functional
+- The C backend has limited effect support (Console, File only - no HttpServer, Http, etc.)
+
+## CLI Commands & Aliases
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `lux fmt` | `lux f` | Format .lux files |
+| `lux test` | `lux t` | Run test suite |
+| `lux check` | `lux k` | Type check + lint |
+| `lux lint` | `lux l` | Lint only (with `--explain` for detailed help) |
+| `lux serve` | `lux s` | Static file server |
+| `lux compile` | `lux c` | Compile to binary |
+
+## Code Quality
+
+- Fix all compiler warnings before committing
+- Ensure all tests pass (currently 381 tests)
+- Add new tests when adding features
+- Keep examples and documentation in sync
+
+## Lux Language Notes
+
+### Top-level expressions
+Bare `run` expressions are not allowed at top-level. You must wrap them in a `let` binding:
+```lux
+// WRONG: parse error
+run main() with {}
+
+// CORRECT
+let output = run main() with {}
+```
+
+### String methods
+Lux uses module-qualified function calls, not method syntax on primitives:
+```lux
+// WRONG: not valid syntax
+path.endsWith(".html")
+
+// CORRECT
+String.endsWith(path, ".html")
+```
+
+### Available String functions
+Key string functions (all in `String.` namespace):
+- `String.length(s)` - get length
+- `String.startsWith(s, prefix)` - check prefix
+- `String.endsWith(s, suffix)` - check suffix
+- `String.split(s, delimiter)` - split into list
+- `String.join(list, delimiter)` - join list
+- `String.substring(s, start, end)` - extract substring
+- `String.indexOf(s, needle)` - find position (returns Option)
+- `String.replace(s, old, new)` - replace occurrences
+- `String.trim(s)` - trim whitespace
+- `String.toLower(s)` / `String.toUpper(s)` - case conversion