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

Installation

User Prerequisite

Install the Claude Code CLI and keep claude on PATH for the account and management operations listed in Claude CLI dependencies. Core sessions use the bundled Agent SDK; the CLI is also an optional usage-data source or fallback. See anthropics/claude-code for how to install it.

The recommended script install includes the application and its runtime dependencies. It does not require a Rust toolchain, Node.js, npm, or a separate Bun installation.

Install Script

Install scripts are available in GitHub Releases starting with v0.14.0 and are the recommended install path. They install a self-contained release without requiring npm, Node.js, or Bun on the user’s machine.

The scripts download a complete release archive from GitHub, verify the release archive integrity, install the native binary with the bundled private Bun runtime, Agent SDK bridge, and production node_modules, then run a quiet claude-rs --version check. Download diagnostics and strict runtime diagnostics are available with the opt-in verify flag.

Interactive terminals display a fixed-width 20-cell progress bar while downloading the release archive and a spinner for other longer installation steps. Transferred size and total size are shown when they fit; the verify flag adds average speed and ETA, followed by the final transfer size, elapsed time, average speed, and HTTP status. Details that would wrap are omitted from the live line. Redirected output and CI remain plain and log-friendly, and NO_COLOR disables colored status output.

On supported interactive terminals, confirmation prompts show y Yes / N No and accept either answer key immediately, without Enter. Other keys are ignored. Terminals without single-key input use a line prompt instead, where Enter selects No.

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh

Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

The default Unix install layout is:

${XDG_DATA_HOME:-$HOME/.local/share}/claude-rs/
$HOME/.local/bin/claude-rs
$HOME/.local/share/man/man1/claude-rs*.1

The app directory contains claude-rs, claude-rs-bridge-bun, agent-sdk/, and node_modules/. The file in $HOME/.local/bin is a launcher script that executes the app binary. Unix archives also contain manuals under share/man/man1/; the installer links them into the sibling share/man/man1/ directory beside bin. Uninstall removes its own manual links and preserves manuals from other installations. See Usage for viewing manuals and generating them with npm or source installations.

The default Windows install layout is:

%LOCALAPPDATA%\Programs\claude-rs\

The Windows app directory is added to the user Path unless path modification is disabled.

Install From npm

npm remains supported for users who prefer package-manager ownership of the global command:

npm install -g claude-code-rust
claude-rs --version
claude-rs

The npm option requires Node.js 24 and npm to install and run its JavaScript launcher. The package owns the claude-rs command, selects the matching platform payload with npm optional dependencies, and includes the private Bun runtime used by the Agent SDK bridge. A Rust toolchain and separate Bun installation are not required. No install-time binary download or postinstall script is used.

Supported npm platforms are Linux x64/arm64 with glibc, Windows x64/arm64, and macOS x64/arm64.

Pinning a Release

Use CLAUDE_RS_RELEASE to install a specific release:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | CLAUDE_RS_RELEASE=v0.14.0 sh

$env:CLAUDE_RS_RELEASE = "v0.14.0"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

The version can include or omit the v prefix.

Reinstalling the Same Version

Before downloading release checksums or an archive, the installer compares the selected release with the version recorded in an existing script-owned install at the configured install directory. It does not compare with an npm install or another claude-rs found on PATH, because those may represent a different installation method or location.

When the selected version is already installed, an interactive installation asks whether to reinstall it and defaults to no. Declining is a successful no-op and leaves the existing files unchanged. In CI or another non-interactive environment, the same-version check also exits successfully without reinstalling.

Use --yes or -Yes to approve an intentional same-version reinstall, for example to repair an installation:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --release v0.14.0 --yes

.\install.ps1 -Release v0.14.0 -Yes

Update mode always treats an already-installed selected version as a successful no-op, even though update mode otherwise runs non-interactively. With the default latest selection, the installer must first request GitHub Release metadata to resolve the release tag; the same-version guard still runs before downloading SHA256SUMS or the release archive.

Custom Install Locations

Choosing a custom install directory creates or updates the installation at that location; it does not move or automatically uninstall a copy in the default directory. A temporary test installation can therefore coexist with your normal installation. Decline its optional cleanup prompt to keep the normal copy.

On macOS/Linux, pass installer flags after sh -s --:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --install-dir "$HOME/.local/share/claude-rs" --bin-dir "$HOME/.local/bin"

For non-interactive Unix installs:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --yes

The Unix installer also accepts:

  • --release <version>
  • --install-dir <dir>
  • --bin-dir <dir>
  • --yes or -y
  • --non-interactive
  • --no-modify-path
  • --verify
  • --run
  • --remove-npm
  • --keep-npm
  • --uninstall
  • --update

When using the PowerShell one-liner, configure the installer with environment variables because arguments cannot be passed through iex:

$env:CLAUDE_RS_INSTALL_DIR = "$env:LOCALAPPDATA\Programs\claude-rs"
$env:CLAUDE_RS_NO_MODIFY_PATH = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

If you download the script first, PowerShell flags are also available:

.\install.ps1 -Release v0.14.0 -InstallDir "$env:LOCALAPPDATA\Programs\claude-rs" -NoModifyPath

Other PowerShell flags available when the script is downloaded first:

  • -Yes
  • -Verify
  • -Run
  • -RemoveNpm
  • -KeepNpm
  • -Uninstall
  • -Update

With the PowerShell one-liner, use the matching environment variables:

  • CLAUDE_RS_VERIFY=1
  • CLAUDE_RS_RUN=1
  • CLAUDE_RS_REMOVE_NPM=1
  • CLAUDE_RS_KEEP_NPM=1
  • CLAUDE_RS_UNINSTALL=1

After a successful install, an interactive run asks whether to start claude-rs immediately. This runs the installed binary directly, so it works even before a new shell picks up PATH changes. Use --run, -Run, or CLAUDE_RS_RUN=1 to start it automatically after install.

When the startup update screen offers Install update, it detects whether the running executable is owned by a script or npm install and uses the same method. Script updates replace the existing app directory while preserving its launcher and PATH configuration. If the executable is not in a recognized install layout, the screen offers separate script and npm choices instead of guessing from PATH order.

The /config setting Automatic updates defaults to Off, retaining that manual update screen. Turning it On skips the screen and installs an available newer version in the background after a normal exit. Update checks continue in either mode. Automatic installation uses only a recognized script or npm layout and selects the checked release version; an unrecognized source build is left untouched. See Settings.

Supported Script Platforms

Install archives are published for Linux x64/arm64 with glibc, Windows x64/arm64, and macOS x64/arm64.

Linux musl distributions are not supported by the install archives yet. Use npm if your platform has a matching package, or build from source.

The scripts do not require user-installed Node.js or Bun. If npm is available and a global claude-code-rust install is present, the installer identifies its location and offers to uninstall it through npm after the new script installation has passed verification. If the selected release does not contain install archives, the installer exits with:

install script is currently not available for this release

Switching Install Methods

claude-rs is resolved by normal PATH order. npm and script installs use different app layouts, and one method does not automatically own files created by the other. If both are installed, whichever claude-rs appears first on PATH runs.

After verifying a new installation, the installer reports recognized other script installations on PATH and offers to uninstall each one with y Yes / N No. The question names the exact app directory; another copy is not necessarily older. Confirming removes that copy and its owned launcher, manual links, and managed PATH configuration where applicable. Unknown copies receive manual guidance, and installations whose directories overlap the current app or launcher are kept. Different PATH spellings, symlinks, and junctions pointing to the current installation do not produce a duplicate-install prompt.

Declining keeps the other installation. --yes / -Yes and non-interactive runs skip optional cleanup and preserve other script copies. They also keep a detected npm installation unless you explicitly request npm removal with --remove-npm, -RemoveNpm, or CLAUDE_RS_REMOVE_NPM=1. Update mode preserves other installations and does not offer cleanup. Cleanup failures are reported without failing the completed new installation.

To see every visible claude-rs on macOS/Linux:

command -v claude-rs
which -a claude-rs

To see every visible claude-rs on Windows:

Get-Command claude-rs -All

To switch from npm to the install script, either let the installer prompt you or pass the explicit removal flag:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --remove-npm

$env:CLAUDE_RS_REMOVE_NPM = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"
Remove-Item Env:\CLAUDE_RS_REMOVE_NPM

To switch from the install script back to npm, uninstall the script layout first, then install from npm:

npm install -g claude-code-rust

The installers do not silently remove the other install method because that would delete files outside their ownership and can be surprising in managed environments. For non-interactive installs, use --remove-npm / CLAUDE_RS_REMOVE_NPM=1 when you want the script installer to remove the npm install, or --keep-npm / CLAUDE_RS_KEEP_NPM=1 when you want it kept without prompting.

If the wrong claude-rs runs after switching methods, see Troubleshooting.

Uninstall

Remove a script install on macOS/Linux with --uninstall:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --uninstall

On Windows, PowerShell supports -Uninstall when the script is downloaded first:

.\install.ps1 -Uninstall

With the PowerShell one-liner, arguments cannot be passed through iex, so use CLAUDE_RS_UNINSTALL:

$env:CLAUDE_RS_UNINSTALL = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"
Remove-Item Env:\CLAUDE_RS_UNINSTALL

The script uninstall path removes the script install directory, removes the Unix launcher when it points at that directory, and removes installer-managed PATH entries where supported. It refuses to delete an app directory that does not look like a claude-code-rust script install.

An npm install is owned by npm and is removed with npm:

npm uninstall -g claude-code-rust

Reporting Install Problems

Include:

  • install method
  • OS and architecture
  • terminal
  • npm --version, for npm installs
  • npm config get omit, for npm installs
  • claude-rs --version
  • claude-rs doctor --json
  • the command you ran
  • the exact error output