diff --git a/README.md b/README.md
index 5c7d5ed..5da1947 100644
--- a/README.md
+++ b/README.md
@@ -411,7 +411,15 @@ npm run check:extension   # type-check, build extension/background.js, syntax-ch
 uv run pytest -q
 ```
 
-The extension source lives in `extension/src/`. `extension/background.js` is generated and ignored by git. Run `npm run build:extension` before using `Load unpacked` with `extension/`.
+On NixOS or hosts without global Node/npm:
+
+```sh
+nix-shell
+npm ci
+npm run check:extension
+```
+
+The extension source lives in `extension/src/`. `extension/background.js` is generated and ignored by git. Run `npm run build:extension` before using `Load unpacked` with `extension/`. On NixOS, use `nix-shell` first if npm is not installed globally.
 
 ---
 
diff --git a/shell.nix b/shell.nix
new file mode 100644
index 0000000..b853b3b
--- /dev/null
+++ b/shell.nix
@@ -0,0 +1,13 @@
+{ pkgs ? import <nixpkgs> {} }:
+
+pkgs.mkShell {
+  packages = with pkgs; [
+    nodejs_22
+    uv
+    python3
+  ];
+
+  shellHook = ''
+    echo "browser-cli dev shell: node $(node --version), npm $(npm --version), uv $(uv --version)"
+  '';
+}