diff --git a/README.md b/README.md
index 5da1947..2ad49ba 100644
--- a/README.md
+++ b/README.md
@@ -414,8 +414,7 @@ uv run pytest -q
 On NixOS or hosts without global Node/npm:
 
 ```sh
-nix-shell
-npm ci
+nix-shell   # automatically runs npm ci when node_modules is missing/outdated
 npm run check:extension
 ```
 
diff --git a/shell.nix b/shell.nix
index b853b3b..ba96c61 100644
--- a/shell.nix
+++ b/shell.nix
@@ -9,5 +9,12 @@ pkgs.mkShell {
 
   shellHook = ''
     echo "browser-cli dev shell: node $(node --version), npm $(npm --version), uv $(uv --version)"
+
+    if [ -f package-lock.json ]; then
+      if [ ! -f node_modules/.package-lock.json ] || [ package-lock.json -nt node_modules/.package-lock.json ]; then
+        echo "Installing extension dependencies with npm ci..."
+        npm ci
+      fi
+    fi
   '';
 }