diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4314fda
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,56 @@
+# NixOS Configuration
+
+This is a NixOS flake configuration managing multiple machines.
+
+## Adding Packages
+
+**User packages** go in `home/googlebot.nix`:
+- Development tools, editors, language-specific tools
+- Use `home.packages` for CLI tools
+- Use `programs.<name>` for configurable programs (preferred when available)
+- Gate dev tools with `thisMachineIsPersonal` so they only install on workstations
+
+**System packages** go in `common/default.nix`:
+- Basic utilities needed on every machine (servers and workstations)
+- Examples: git, htop, tmux, wget, dnsutils
+- Keep this minimal - most packages belong in home/googlebot.nix
+
+**Personal machine system packages** go in `common/pc/default.nix`:
+- Packages that must be system-level (not per-user) due to technical limitations
+- But only needed on personal/development machines, not servers
+- Examples: packages requiring udev rules, system services, or setuid
+
+## Machine Roles
+
+Machines have roles defined in their configuration:
+
+- **personal**: Development workstations (desktops, laptops). Install dev tools, GUI apps, editors here.
+- **Non-personal**: Servers and production machines. Keep minimal.
+
+Use `thisMachineIsPersonal` (or `osConfig.thisMachine.hasRole."personal"`) to conditionally include packages:
+
+```nix
+home.packages = lib.mkIf thisMachineIsPersonal [
+  pkgs.some-dev-tool
+];
+```
+
+## Sandboxed Workspaces
+
+Isolated development environments using VMs or containers. See `skills/create-workspace/SKILL.md`.
+
+- VMs: Full kernel isolation via microvm.nix
+- Containers: Lighter weight via systemd-nspawn
+
+Configuration: `common/sandboxed-workspace/`
+
+## Key Directories
+
+- `common/` - Shared NixOS modules for all machines
+- `home/` - Home Manager configurations
+- `machines/` - Per-machine configurations
+- `skills/` - Claude Code skills for common tasks
+
+## Git Commits
+
+Do not add "Co-Authored-By" lines to commit messages.