claude-code: manifest + updateScript, bump to 2.1.156 (#304)

andrewgazelka · web-flow · commit 67be91ba8632 · 2026-05-29T18:30:35.000Z
Bumps Claude Code to 2.1.156 and replaces the hand-maintained
version/hash pin with the nixpkgs pattern: a generated `manifest.json`
read via `lib.importJSON` plus a `passthru.updateScript`.

## Why
The previous `default.nix` pinned the version and four per-platform SRI
hashes inline behind a 14-line comment describing a manual "re-prefetch
each platform binary" loop. Anthropic actually publishes a per-version
`manifest.json` on the GCS bucket (every platform's checksum in one
file) plus a `latest` pointer, so the four-prefetch dance was never
necessary. nixpkgs already consumes that manifest; this brings our
package in line.

## What changed
- `packages/claude-code/manifest.json` (generated): version + per-system
`{ slug, hash }`. SRI, not the hex upstream ships (repo ast-grep bans
`sha256 =` hex in fetchers).
- `packages/claude-code/default.nix`: reads the manifest, derives the
fetch URL/hash from it, and exposes `passthru.updateScript`. The
system→slug map now lives only in the updater (single owner);
`default.nix` reads the slug back from the manifest.
- `lib/packages.nix`: injects a pkgs-applied `writeNushellApplication`
into the flake package-set context so the updater can build. The overlay
context does not provide it, so `pkgs.claude-code` (consumed by the dev
image) simply omits `updateScript`; the flake output `.#claude-code`
carries it.
- `agents-md/sections/13-dependency-intake.md` (+ regenerated
`AGENTS.md`/`CLAUDE.md`): one durable note that prebuilt-binary packages
own a generated manifest + updateScript and are bumped by running the
updater.

## Bumping going forward
```sh
nix run .#claude-code.updateScript -- &lt;version&gt;   # omit version to track `latest`
```
It refetches the upstream manifest, converts hex→SRI, and rewrites
`manifest.json`.

## Validation
- `nix build .#claude-code` builds 2.1.156 (hashes match).
- `nix run .#claude-code.updateScript -- 2.1.156` reproduces the
committed `manifest.json` byte-for-byte.
- Overlay eval: `pkgs.claude-code.version == "2.1.156"`, `? updateScript
== false` (no missing-arg error).
- `nix run .#lint` clean.
diff --git a/AGENTS.md b/AGENTS.md
@@ -606,6 +606,14 @@ lock output that makes later builds pure.
 Generated catalogs are build inputs, not hand-edited source. If a generated file
 is wrong, change the manifest or generator that owns it.
 
+A prebuilt-binary package pins its version and per-platform hashes in a generated
+`manifest.json` read with `lib.importJSON` and refreshed by a
+`passthru.updateScript`; bump by running the updater, never by hand-editing the
+hashes. When upstream signs its release manifest, the updater verifies that
+signature against a pinned key and fails closed before writing hashes. See
+[`packages/claude-code`](packages/claude-code) for the worked shape:
+`nix run .#claude-code.updateScript -- <version>`.
+
 Keep binary and generated artifacts near the owner that can explain and refresh
 them. Use small manifests for curated sets, generated catalogs for URLs and
 hashes, and metadata catalogs for search or browsing surfaces.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -606,6 +606,14 @@ lock output that makes later builds pure.
 Generated catalogs are build inputs, not hand-edited source. If a generated file
 is wrong, change the manifest or generator that owns it.
 
+A prebuilt-binary package pins its version and per-platform hashes in a generated
+`manifest.json` read with `lib.importJSON` and refreshed by a
+`passthru.updateScript`; bump by running the updater, never by hand-editing the
+hashes. When upstream signs its release manifest, the updater verifies that
+signature against a pinned key and fails closed before writing hashes. See
+[`packages/claude-code`](packages/claude-code) for the worked shape:
+`nix run .#claude-code.updateScript -- <version>`.
+
 Keep binary and generated artifacts near the owner that can explain and refresh
 them. Use small manifests for curated sets, generated catalogs for URLs and
 hashes, and metadata catalogs for search or browsing surfaces.
diff --git a/agents-md/sections/13-dependency-intake.md b/agents-md/sections/13-dependency-intake.md
@@ -26,6 +26,14 @@ lock output that makes later builds pure.
 Generated catalogs are build inputs, not hand-edited source. If a generated file
 is wrong, change the manifest or generator that owns it.
 
+A prebuilt-binary package pins its version and per-platform hashes in a generated
+`manifest.json` read with `lib.importJSON` and refreshed by a
+`passthru.updateScript`; bump by running the updater, never by hand-editing the
+hashes. When upstream signs its release manifest, the updater verifies that
+signature against a pinned key and fails closed before writing hashes. See
+[`packages/claude-code`](packages/claude-code) for the worked shape:
+`nix run .#claude-code.updateScript -- <version>`.
+
 Keep binary and generated artifacts near the owner that can explain and refresh
 them. Use small manifests for curated sets, generated catalogs for URLs and
 hashes, and metadata catalogs for search or browsing surfaces.
diff --git a/lib/packages.nix b/lib/packages.nix
@@ -30,6 +30,9 @@ let
       ixForPackages
       ;
     ix = ixForPackages;
+    # Pre-applied to the caller's pkgs so flake-output packages can build a
+    # `passthru.updateScript` without re-threading `ix` through callPackage.
+    writeNushellApplication = ixForPackages.writeNushellApplication pkgs;
   };
   mergePackageTrees =
     left: right:
diff --git a/packages/claude-code/default.nix b/packages/claude-code/default.nix
@@ -8,51 +8,30 @@
   ripgrep,
   bubblewrap,
   socat,
+  nix,
+  gnupg,
   binName ? "claude",
+  # Only the flake package set injects the Nushell writer; the overlay eval
+  # context does not. The updater is a maintainer-facing flake output, so the
+  # overlay build of `pkgs.claude-code` simply omits `passthru.updateScript`.
+  writeNushellApplication ? null,
 }:
 
 let
-  # Pinned to a prerelease build on purpose. Anthropic publishes new Claude
-  # Code versions to the npm `next` (prerelease) tag days before promoting
-  # them to `latest` (stable), and every channel that normally surfaces an
-  # upgrade only watches `latest`: the built-in `claude` auto-updater and
-  # `claude doctor` both reported "up to date", and sadjow/claude-code-nix
-  # (the usual Nix source) tracks stable too. At the Opus 4.8 launch 2.1.154
-  # sat on `next` while everything else still showed 2.1.153, yet 2.1.154 is
-  # the first build that defaults `/fast` to Opus 4.8. Fetching the platform
-  # binary directly by version is the only way to pin ahead of the stable
-  # promotion. When `latest` catches up, this can fall back to a channel that
-  # tracks stable. Bump by re-prefetching each platform binary:
-  #   nix store prefetch-file --json \
-  #     https://downloads.claude.ai/claude-code-releases/<version>/<slug>/claude
-  version = "2.1.154";
-
-  # Claude Code ships prebuilt Bun single-file executables per platform. The
-  # download path keys off Anthropic's own platform slugs rather than the Nix
-  # system doubles, so map between them here.
-  platforms = {
-    aarch64-darwin = {
-      slug = "darwin-arm64";
-      hash = "sha256-vJiBsQfXvhdDxkyLct1meY9dCUfbxI7Q13lkxHNmH9Q=";
-    };
-    x86_64-darwin = {
-      slug = "darwin-x64";
-      hash = "sha256-FgjZMmGHkgHc933TLcFz777qcVGH01Qv0Fr899W17E0=";
-    };
-    x86_64-linux = {
-      slug = "linux-x64";
-      hash = "sha256-Z/bKt+bBJAEPYqwY+AeLwJ4NtqW56K6HTp5zAzxFF5M=";
-    };
-    aarch64-linux = {
-      slug = "linux-arm64";
-      hash = "sha256-n3Mt4nj3rcYdKf1bBV3a8brjuybXX+bgahJWAlZXd6g=";
-    };
-  };
+  # Version and per-platform SRI hashes are generated, never hand-edited. Bump
+  # with `nix run .#claude-code.updateScript -- <version>`, which refetches
+  # Anthropic's per-version manifest and rewrites manifest.json. We pin by raw
+  # version (not the npm `latest` tag) because Anthropic ships new builds to the
+  # `next` prerelease tag days before promoting them to `latest`, and every
+  # channel that normally surfaces an upgrade (the built-in updater, `claude
+  # doctor`, sadjow/claude-code-nix) only watches `latest`.
+  manifest = lib.importJSON ./manifest.json;
+  inherit (manifest) version;
 
   inherit (stdenv.hostPlatform) system;
   target =
-    platforms.${system}
-      or (throw "claude-code: no prebuilt binary for ${system}; supported: ${lib.concatStringsSep ", " (builtins.attrNames platforms)}");
+    manifest.platforms.${system}
+      or (throw "claude-code: no prebuilt binary for ${system}; supported: ${lib.concatStringsSep ", " (builtins.attrNames manifest.platforms)}");
 
   # Primary host is the Anthropic-branded CDN so the source is verifiable; the
   # GCS bucket is the direct origin and stays as a mirror if the CDN is down.
@@ -65,6 +44,75 @@ let
     ];
     inherit (target) hash;
   };
+
+  # Refreshes manifest.json from Anthropic's published per-version manifest,
+  # converting its hex checksums to the SRI hashes the fetcher pins. The slug
+  # map lives here as the single owner; default.nix only reads it back. The
+  # updater fails closed unless the manifest's detached GPG signature verifies
+  # against the pinned release signing key (release-signing-key.asc, fingerprint
+  # 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE, published at
+  # downloads.claude.ai/keys/claude-code.asc), so a spoofed manifest cannot
+  # inject hashes for attacker-controlled binaries.
+  updateScript =
+    if writeNushellApplication == null then
+      null
+    else
+      writeNushellApplication {
+        name = "claude-code-update";
+        runtimeInputs = [
+          nix
+          gnupg
+        ];
+        meta.description = "Refresh packages/claude-code/manifest.json to a signed Claude Code release";
+        text = ''
+          const base = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
+          const signing_key = "${./release-signing-key.asc}"
+          const slugs = {
+            "aarch64-darwin": "darwin-arm64",
+            "x86_64-darwin": "darwin-x64",
+            "x86_64-linux": "linux-x64",
+            "aarch64-linux": "linux-arm64"
+          }
+
+          # Run from the repo root: `nix run .#claude-code.updateScript -- [version]`.
+          # Without a version argument it tracks Anthropic's `latest` pointer.
+          def main [version?: string] {
+            let v = ($version | default (http get $"($base)/latest" | str trim))
+
+            # Download the exact bytes we verify, then parse the same file.
+            let work = (mktemp --directory)
+            let manifest_path = $"($work)/manifest.json"
+            let sig_path = $"($work)/manifest.json.sig"
+            http get --raw $"($base)/($v)/manifest.json" | save --force $manifest_path
+            http get --raw $"($base)/($v)/manifest.json.sig" | save --force $sig_path
+
+            # Fail closed: only the pinned key lives in this GNUPGHOME, so a
+            # zero exit from --verify proves Anthropic signed these exact bytes.
+            let gnupghome = (mktemp --directory)
+            with-env { GNUPGHOME: $gnupghome } {
+              ^gpg --batch --quiet --import $signing_key
+              let check = (do { ^gpg --batch --verify $sig_path $manifest_path } | complete)
+              if $check.exit_code != 0 {
+                error make { msg: $"claude-code: manifest signature verification failed for ($v)\n($check.stderr)" }
+              }
+            }
+
+            let upstream = (open $manifest_path)
+            let platforms = (
+              $slugs
+              | transpose system slug
+              | reduce --fold {} {|row acc|
+                  let hex = ($upstream.platforms | get $row.slug | get checksum)
+                  let sri = (^nix hash convert --hash-algo sha256 --to sri $hex | str trim)
+                  $acc | insert $row.system { slug: $row.slug, hash: $sri }
+                }
+            )
+            let out = "packages/claude-code/manifest.json"
+            { version: $v, platforms: $platforms } | to json --indent 2 | save --force $out
+            print $"updated ($out) to ($v); signature verified"
+          }
+        '';
+      };
 in
 stdenv.mkDerivation {
   pname = "claude-code";
@@ -111,6 +159,10 @@ stdenv.mkDerivation {
     runHook postInstall
   '';
 
+  passthru = lib.optionalAttrs (updateScript != null) {
+    inherit updateScript;
+  };
+
   meta = {
     description = "Claude Code, Anthropic's agentic coding tool in the terminal";
     homepage = "https://www.anthropic.com/claude-code";
@@ -120,7 +172,7 @@ stdenv.mkDerivation {
     # `nix run .#claude-code`. Distribution terms are Anthropic's commercial
     # Claude Code license.
     mainProgram = binName;
-    platforms = builtins.attrNames platforms;
+    platforms = builtins.attrNames manifest.platforms;
     sourceProvenance = [ lib.sourceTypes.binaryNativeCode ];
   };
 }
diff --git a/packages/claude-code/manifest.json b/packages/claude-code/manifest.json
@@ -0,0 +1,21 @@
+{
+  "version": "2.1.156",
+  "platforms": {
+    "aarch64-darwin": {
+      "slug": "darwin-arm64",
+      "hash": "sha256-nB6GAQMfXLsxAeSd2iK/i6MRg2kscF4memkjWF+iugk="
+    },
+    "x86_64-darwin": {
+      "slug": "darwin-x64",
+      "hash": "sha256-zNYIxpRncyTiTex9ElO1H4h6e+g4zbdbItU2LJc1EQc="
+    },
+    "x86_64-linux": {
+      "slug": "linux-x64",
+      "hash": "sha256-bYPNImRFDF5U/JiL4QMsKIz0GO5gQpSs+4/ErCj196M="
+    },
+    "aarch64-linux": {
+      "slug": "linux-arm64",
+      "hash": "sha256-ftldCpOutA4rmOI0t2DZKVtwRO9njGLbjR9eFL/VeHg="
+    }
+  }
+}
diff --git a/packages/claude-code/release-signing-key.asc b/packages/claude-code/release-signing-key.asc
@@ -0,0 +1,29 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQINBGnK73ABEACnbytJXkjweYrwIr0aLEFRlH+C0nF44KxFc7gQmJ6PjSPMGZAD
+dxZcaixU7zZl8WxEpVO0wLmIH8cf2zGOdyuZg1Yaugk1vHb2b8WBhAGCQJdPgB8W
+XquedepEYtk56uP/gCoTjJDUZluEGBHnlnuujSJ4orxEdhSykEoAUfJZGEILPpMd
+bphFt/Sn+Eb/TxM5jpKPdwnv8AShNF/1mZU1fWTQq9tRKJUakZj04gdaDFElQXak
+CtTij+GT6yoYCARSHwGO+PC/Pr6q4tc+D7LRjxSBvUWDoFSmlqb/PJ1hj9D/7I2O
+e4XXniAPWMR56KvxHlzOzrNQdJujbJdSkCwh1ZijkSd3y8ayW5WYUTGdRab99NUw
+agzlabe/VVF6kzJ0Scn5q3PihB2Y9Bwo0CKnkYk7a7KT77EWv0Kkq+VHmOtqX3a2
+hhX+b6a6ve9rzJ1qZYGj+obv/C3Sx1LzUjAfqVy7RJDf2uAoP5t2g8u/TkSpUxhM
+VEjZBkSxYZhMyzQM6t8IgkUfnSrIPTHixbDWARZ4beMOBjxyPZK1nP7OOrNR3TkK
+JtwLMQAabURCDnL0PjS0iwBTU4jtumBD1XSULyWuoTvMljrpQr1nV1oDyOt0OLqa
+KA2McWtd9PdXhC8y2EIg7TmrTlJLfHYbdmkiCYj4J49Q8HWkN/6WE+RTUwARAQAB
+tD5BbnRocm9waWMgQ2xhdWRlIENvZGUgUmVsZWFzZSBTaWduaW5nIDxzZWN1cml0
+eUBhbnRocm9waWMuY29tPokCUQQTAQoAOxYhBDHd3iTd+rZ59C170rqpKf8afsrO
+BQJpyu9wAhsPBQsJCAcCAiICBhUKCQgLAgQWAgMBAh4HAheAAAoJELqpKf8afsrO
+l5IP/2I8X1dFy5xYczWB/coIxGjuzS/V6ByZGZZEJsbr04pmuHiFUykJqPGWGQ6q
+U0YF5iEwvEkaagS5m7DzhSEf3FM3Cgafax/6d70tar9Vr1D+w6uPfxetu7u/WYJp
+aolIsdh5fTrBh9zSM1Njl8FM8wG8CwZQjS33Oa7d8cwRkgdUWbt6LXgz+cTQNuBn
+BgW6Ks7oZFI25dfu0ojDR+aDFJg4+4wZoyDLPvJz1SIrJ5WFGs67zsx9SfS3yZnf
+XKmBe+f0dUy+GJ2nFZrXFf99+c0dPEHYO8DCeAHZizjkFrdYtUHdDU0YDYEGkLJa
+bE+pgcpkHf5EvsZzHsyDbl95W/eh7pcXMbwkN+W4CBYUE9X4uHhqzWaC5yAVRWUA
+1BJ9V4LjZfHPLEJt0I3TxzXiEg9/BVeaTYq9RjaxIFo9Nfk158HqJY6SA5jslBlx
+Gv/No8u+xVcze2UJyGVfEIUfm92+0UAIkny3+5cuVV0ICzJxXlXj0CnLM9Lt50wE
+p3suVwuBEviCbZ08eAH1Ht8gbBdSsiOkIU8CX3v/scwHHx5q0+NBL6xLrQObg13a
+tRXBlKObfElkPN3lTUbUnJOW4U8uSjH8VRP+AujKWMDFe7x0zCs+iYY1mTOvbrTS
+9n3CmZUmbynZ+E/QWNENpW/pDNZdWFy43PASmML5FHu4m9Sn
+=oqMI
+-----END PGP PUBLIC KEY BLOCK-----
