Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Packaging and release invariants

This page is for maintainers changing installation or release packaging. For installing the app, use Installation; for a local checkout, use Development. Release workflow changes are maintainer-owned. Governance owns approval and publication policy.

Packaging

The npm install is split across a root command package and platform payload packages.

The root package is claude-code-rust. It exposes the claude-rs command through the npm launcher and includes the built Agent SDK bridge under:

bin/claude-rs.js
agent-sdk/dist/bridge.js

The platform packages are selected through root package optional dependencies. They include the native Rust binary and private Bun runtime. The exact package mapping lives in scripts/shared/npm-package-config.mjs; supported npm payloads currently cover Linux x64/arm64 glibc, Windows x64/arm64, and macOS x64/arm64.

At runtime, npm’s generated shim starts bin/claude-rs.js. The launcher selects the matching platform package, sets CLAUDE_RS_AGENT_BRIDGE to the root package bridge script, and spawns the native binary. The native binary resolves the bundled Bun runtime from the platform package bin/ directory. No npm postinstall script, install-time binary download, or global Bun is required.

Release Model

Release packaging is designed around immutable artifacts:

  • Native binaries are built on GitHub-hosted runners for Linux x64 glibc, Linux arm64 glibc, Windows x64, Windows arm64, macOS x64, and macOS arm64.
  • Private Bun runtime files are staged into each platform package as third-party runtime artifacts.
  • Generated npm package directories are verified against allowlisted package contents before packing.
  • Unix install archives include man pages generated by the packaging host’s staged native binary. The Unix installer links those pages beside its command directory and removes only its own links on uninstall.
  • Packed npm tarballs are smoke-tested before publication.
  • GitHub Releases include native binaries, npm tarballs, package-content manifests, build metadata, and SHA256SUMS.
  • The release workflow generates and verifies build provenance attestations for native binaries before npm publication.
  • npm publication uses Trusted Publishing rather than a long-lived npm token.
  • The root package remains the user-facing npm install package and depends optionally on platform payload packages.

Source builds are different: cargo build or cargo install --path . produce only the Rust binary. They do not build or install the JavaScript bridge or private Bun runtime. Build the bridge with Node.js 24/npm and provide it through the checkout fallback, --bridge-script, or CLAUDE_RS_AGENT_BRIDGE. Debug builds can use CLAUDE_RS_AGENT_BRIDGE_RUNTIME to point at a local Bun runtime; release npm installs use only the bundled runtime. See Development for the exact steps.

Artifact invariants

Important invariants:

  • The root npm package must not use postinstall or install-time binary downloads.
  • The root npm package owns the claude-rs bin through bin/claude-rs.js.
  • Native binaries and private Bun runtimes live in platform-specific optional npm packages.
  • Platform packages must not expose their own npm claude-rs bin; otherwise npm can link the payload package over the root resolver.
  • Platform packages must publish before the root package for a given version.
  • Release artifacts should be generated, verified, packed, and smoke-tested before publication.

Validate packaging changes

Follow the npm-package-layout job in pr.yml for the full local command sequence, prerequisites and mock-payload checks. The scripts guide describes the packaging tools. Mock payload validation checks layout; it does not establish that a real release binary starts. Real-binary and registry smoke checks are separate release validations.

Use the platform mapping in scripts/shared/npm-package-config.mjs when selecting a target. Generated directories (dist-npm/, dist-install/ and dist-pack/) are outputs; change their generators rather than editing them.

Do not trigger releases, create tags or publish npm packages from contributor PRs.