How the CodeWhale Binary Download Process Works: NPM Wrapper & GitHub Releases

The CodeWhale binary download process uses an npm-wrapper post-install script that automatically fetches platform-specific pre-built artifacts from GitHub Releases, verifies SHA-256 checksums, and caches them locally with support for retries, timeouts, and environment-variable overrides.

The Hmbown/CodeWhale repository distributes its CLI through an npm wrapper that eliminates manual binary management. During installation, a post-install script automatically detects your platform, downloads the appropriate pre-built binary, and verifies its cryptographic hash before caching it for future use.

Step 1: Determine the Target Asset

The download begins in npm/codewhale/scripts/artifacts.js, where the wrapper constructs the release URL. The script reads the desired version from the DEEPSEEK_TUI_VERSION environment variable or defaults to the package version. It builds a download base URL using the pattern https://github.com/${repo}/releases/download/v${version}/.

You can override the target repository by setting DEEPSEEK_TUI_GITHUB_REPO, allowing forks or mirrors to serve custom binaries.

Step 2: Select the Platform-Specific Binary

In npm/codewhale/scripts/install.js, the script inspects process.platform (linux, darwin, win32) and process.arch (x64, arm64) to select the correct filename. For example, Linux x64 systems receive codewhale-linux-x64, while Windows x64 receives codewhale-windows-x64.exe.

The same platform detection logic appears in web/components/install-binary.tsx, which generates the appropriate command lines for the project's documentation website.

Step 3: Download the Checksum Manifest

Before fetching the binary itself, the script downloads codewhale-artifacts-sha256.txt from the same GitHub Release (around line 1014 of install.js). This manifest contains the SHA-256 hash for every platform-specific asset, enabling integrity verification before the binary executes on your system.

Step 4: Robust Binary Download with Retry Logic

The core download(url, destination, options) routine (lines 887-921 of install.js) implements a resilient HTTP client with several protective mechanisms:

• Retry logic: Automatically retries failed requests up to 5 times via withRetry
• Timeout handling: Configurable overall timeout via downloadTimeoutMs
• Stall detection: Aborts if no bytes are received for the duration specified by downloadStallMs
• Progress reporting: Displays friendly messages like "▸ downloading X (y / z MB)" during the transfer

Step 5: Checksum Verification

After the file lands in a temporary .download file, the script computes its SHA-256 hash (lines 1057-1069 of install.js). It compares this computed hash against the entry from the downloaded manifest. If the hashes differ, the script discards the file and triggers another download attempt.

Step 6: Cache and Atomic Move

Once verification succeeds, the binary moves atomically to bin/downloads/<binary-name>. The script creates a companion marker file (*.sha256) containing the expected hash. Subsequent installations check for this marker and skip re-download unless explicitly forced, significantly speeding up reinstalls and CI builds.

Environment Variables for Customization

The download pipeline respects several environment variables that control behavior without modifying code:

• DEEPSEEK_TUI_DISABLE_INSTALL=1: Completely bypasses the post-install download. Essential for CI environments where binaries are pre-packed or vendored.
• DEEPSEEK_TUI_OPTIONAL_INSTALL=1: Converts download failures into warnings, allowing npm install to succeed even if the binary cannot be fetched.
• DEEPSEEK_TUI_FORCE_DOWNLOAD=1: Forces a fresh download even if a valid cached marker exists, useful when updating to a new patched release.
• DEEPSEEK_TUI_RELEASE_BASE_URL: Replaces the GitHub base URL with an internal mirror or proxy (e.g., https://artifacts.internal.company.com/codewhale).

These controls are documented in lines 1100-1120 of install.js.

Runtime Fallback and Manual Installation

If the CLI executes without a present binary, the same download machinery invokes automatically (lines 1170-1190 of install.js). This runtime fallback ensures users never need manual intervention.

Alternatively, bypass the wrapper entirely by downloading directly from GitHub Releases:

curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-x64
chmod +x codewhale-linux-x64 && ./codewhale-linux-x64 --help

These manual commands are documented in docs/INSTALL.md under "Manual download from GitHub Releases".

Common Installation Scenarios

Standard global installation triggers the automatic download:

npm install -g @codewhale/cli

# Binary downloads to ~/.codewhale/bin/downloads

Force a fresh download (ignore cache markers):

DEEPSEEK_TUI_FORCE_DOWNLOAD=1 npm install -g @codewhale/cli

Skip download in CI (use vendored binaries):

DEEPSEEK_TUI_DISABLE_INSTALL=1 npm ci

Use an internal artifact mirror:

DEEPSEEK_TUI_RELEASE_BASE_URL=https://artifacts.internal.company.com/codewhale npm install

Key Source Files

• npm/codewhale/scripts/install.js: Core implementation containing URL construction, retry logic, timeout handling, and checksum verification.
• npm/codewhale/scripts/artifacts.js: Helper functions for building release URLs and locating the local cache directory.
• web/components/install-binary.tsx: React component that displays platform-specific download commands on the project website.
• docs/INSTALL.md: Human-readable installation guide covering environment variables and manual download procedures.
• npm/codewhale/README.md: Summary of wrapper behavior and environment variable reference.

Summary

• The npm wrapper automatically downloads platform-specific binaries from GitHub Releases during npm install.
• SHA-256 checksums are verified against a manifest before the binary executes or moves to its final location.
• Retry logic (up to 5 attempts), timeout handling, and stall detection ensure robust downloads across unreliable networks.
• Environment variables provide fine-grained control for CI pipelines, air-gapped environments, and custom mirrors without code changes.
• Caching with marker files prevents redundant downloads, while runtime fallback ensures the CLI self-heals if the binary is missing.

Frequently Asked Questions

What happens if the download fails during npm install?

If DEEPSEEK_TUI_OPTIONAL_INSTALL is unset, the installation fails with an error describing the HTTP failure or checksum mismatch. When DEEPSEEK_TUI_OPTIONAL_INSTALL=1 is set, the script logs a warning and completes the npm install without the binary, allowing the application to attempt a runtime download later or operate in a limited capacity.

How does CodeWhale determine which binary to download for my system?

The script examines Node.js process.platform and process.arch to map your system to one of the supported artifacts: codewhale-linux-x64, codewhale-darwin-arm64, codewhale-windows-x64.exe, etc. This logic lives in npm/codewhale/scripts/install.js and is shared with the documentation site's install component in web/components/install-binary.tsx.

Can I use a private mirror instead of GitHub Releases?

Yes. Set the DEEPSEEK_TUI_RELEASE_BASE_URL environment variable to your internal mirror's base URL (e.g., https://artifacts.company.com/codewhale). The wrapper will append the version and filename to this base instead of https://github.com/Hmbown/CodeWhale/releases/download/. You can also override the repository path with DEEPSEEK_TUI_GITHUB_REPO if your mirror follows GitHub's URL structure.

How do I verify the downloaded binary hasn't been tampered with?

The download process automatically verifies integrity by comparing the SHA-256 hash of the downloaded file against the entry in codewhale-artifacts-sha256.txt fetched from the same release. If verification fails, the script deletes the corrupted file and retries the download. Manual verification is also possible by running sha256sum codewhale-linux-x64 and comparing the output against the manifest hosted on the official release page.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}