Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

docs: add first-class install scripts

Alishahryar1428746e0e0f2
diff --git a/README.md b/README.md
index 2846a359..86b53592 100644
--- a/README.md
+++ b/README.md
@@ -48,17 +48,25 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code to any p
## Quick Start
-### Fast Install
+### 1. Fast Install
Install or update Claude Code, uv, Python 3.14.0, and Free Claude Code:
+macOS/Linux:
+
```bash
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh
```
-Review the installer at [scripts/install.sh](https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh).
+Windows PowerShell:
+
+```powershell
+irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex
+```
+
+Review the installers at [scripts/install.sh](https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh) and [scripts/install.ps1](https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1).
-### 1. Start The Proxy
+### 2. Start The Proxy
```bash
fcc-server
@@ -72,7 +80,7 @@ INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
Many terminals make these clickable. Use your configured `PORT` if it is not `8082`.
-### 2. Open The Admin UI And Configure NVIDIA NIM
+### 3. Open The Admin UI And Configure NVIDIA NIM
Open the **Admin UI** URL from the terminal output.
@@ -86,7 +94,7 @@ Paste your NVIDIA NIM API key into `NVIDIA_NIM_API_KEY`, then click **Validate**
The default model is already set to `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`. You can change it later from the same Admin UI.
-### 3. Run Claude Code
+### 4. Run Claude Code
```bash
fcc-claude
@@ -329,20 +337,41 @@ The bot wrapper runs Claude Code sessions remotely, streams progress, supports r
### 2. Voice Notes
-Voice notes work on Discord and Telegram after you extend your [Free Claude Code install](#fast-install) with the matching optional extras. Re-run `uv tool install --force` with the extras you need (same Git URL as Quick Start):
+Voice notes work on Discord and Telegram after you extend your [Free Claude Code install](#1-fast-install) with the matching optional extras.
+
+macOS/Linux:
```bash
# NVIDIA NIM transcription (Riva gRPC)
-uv tool install --force "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-nim
# Local Whisper (CPU or CUDA)
-uv tool install --force "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-local
# Both backends
-uv tool install --force "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-all
+
+# Local Whisper with CUDA
+curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-local --torch-backend cu130
+```
+
+Windows PowerShell:
+
+```powershell
+# NVIDIA NIM transcription (Riva gRPC)
+& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceNim
+
+# Local Whisper (CPU or CUDA)
+& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceLocal
+
+# Both backends
+& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceAll
+
+# Local Whisper with CUDA
+& ([scriptblock]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceLocal -TorchBackend cu130
```
-For **cuda** local Whisper, add `--torch-backend cu130` to the `voice_local` install command. Restart `fcc-server` after reinstalling.
+Restart `fcc-server` after reinstalling.
In the **Admin UI**, open **Messaging** and scroll to **Voice**. Turn on **Voice Notes**, choose **Whisper Device** (`cpu`, `cuda`, or `nvidia_nim`), set **Whisper Model**, and enter **Hugging Face Token** when your setup needs it. For **nvidia_nim** transcription, install the `voice` extra and set **NVIDIA NIM API Key** on the **Providers** view. The screenshot above shows the **Voice** block in the same view.
diff --git a/scripts/install.ps1 b/scripts/install.ps1
new file mode 100644
index 00000000..4a1a93d4
--- /dev/null
+++ b/scripts/install.ps1
@@ -0,0 +1,189 @@
+param(
+ [switch] $VoiceNim,
+ [switch] $VoiceLocal,
+ [switch] $VoiceAll,
+ [string] $TorchBackend = "",
+ [switch] $DryRun,
+ [switch] $Help,
+ [Parameter(ValueFromRemainingArguments = $true)]
+ [object[]] $RemainingArgs = @()
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$RepoGitUrl = "git+https://github.com/Alishahryar1/free-claude-code.git"
+$PythonVersion = "3.14.0"
+$UvInstallUrl = "https://astral.sh/uv/install.ps1"
+
+function Show-Usage {
+ @"
+Usage: install.ps1 [options]
+
+Installs or updates Claude Code, uv, Python 3.14.0, and Free Claude Code.
+
+Options:
+ -VoiceNim Install NVIDIA NIM voice transcription support.
+ -VoiceLocal Install local Whisper voice transcription support.
+ -VoiceAll Install all voice transcription backends.
+ -TorchBackend VALUE Use a uv PyTorch backend, such as cu130. Requires local voice.
+ -DryRun Print commands without running them.
+ -Help Show this help text.
+"@
+}
+
+function Write-Step {
+ param([string] $Message)
+
+ Write-Host ""
+ Write-Host "==> $Message"
+}
+
+function Format-Argument {
+ param([string] $Value)
+
+ if ($Value -match '^[A-Za-z0-9_./:@%+=,\[\]-]+$') {
+ return $Value
+ }
+
+ return "'" + ($Value -replace "'", "''") + "'"
+}
+
+function Invoke-InstallCommand {
+ param(
+ [string] $FilePath,
+ [string[]] $Arguments = @()
+ )
+
+ $parts = @($FilePath) + $Arguments
+ $commandText = ($parts | ForEach-Object { Format-Argument ([string] $_) }) -join " "
+ Write-Host "+ $commandText"
+
+ if (-not $DryRun) {
+ & $FilePath @Arguments
+ }
+}
+
+function Invoke-UvInstaller {
+ Write-Host "+ irm $UvInstallUrl | iex"
+
+ if (-not $DryRun) {
+ Invoke-RestMethod $UvInstallUrl | Invoke-Expression
+ }
+}
+
+function Add-PathEntry {
+ param([string] $PathEntry)
+
+ if ([string]::IsNullOrWhiteSpace($PathEntry)) {
+ return
+ }
+
+ $separator = [IO.Path]::PathSeparator
+ $entries = @()
+ if (-not [string]::IsNullOrEmpty($env:Path)) {
+ $entries = $env:Path -split [regex]::Escape([string] $separator)
+ }
+
+ if ($entries -notcontains $PathEntry) {
+ $env:Path = "$PathEntry$separator$env:Path"
+ }
+}
+
+function Add-UvToPath {
+ Add-PathEntry (Join-Path $HOME ".local\bin")
+ Add-PathEntry (Join-Path $HOME ".cargo\bin")
+}
+
+function Assert-CommandAvailable {
+ param([string] $Name)
+
+ if ((-not $DryRun) -and (-not (Get-Command $Name -ErrorAction SilentlyContinue))) {
+ throw "$Name is required. Install it first, then rerun this installer."
+ }
+}
+
+function Install-OrUpdateUv {
+ Add-UvToPath
+
+ if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+ Invoke-UvInstaller
+ Add-UvToPath
+ }
+
+ if ((-not $DryRun) -and (-not (Get-Command uv -ErrorAction SilentlyContinue))) {
+ throw "uv was installed, but it is not available on PATH. Open a new terminal or add uv's bin directory to PATH."
+ }
+
+ Invoke-InstallCommand -FilePath "uv" -Arguments @("self", "update")
+}
+
+function Get-PackageSpec {
+ $includeNim = $VoiceNim
+ $includeLocal = $VoiceLocal
+
+ if ($VoiceAll) {
+ $includeNim = $true
+ $includeLocal = $true
+ }
+
+ if ((-not [string]::IsNullOrWhiteSpace($TorchBackend)) -and (-not $includeLocal)) {
+ throw "-TorchBackend requires -VoiceLocal or -VoiceAll."
+ }
+
+ if ($includeNim -and $includeLocal) {
+ return "free-claude-code[voice,voice_local] @ $RepoGitUrl"
+ }
+
+ if ($includeNim) {
+ return "free-claude-code[voice] @ $RepoGitUrl"
+ }
+
+ if ($includeLocal) {
+ return "free-claude-code[voice_local] @ $RepoGitUrl"
+ }
+
+ return $RepoGitUrl
+}
+
+function Install-FreeClaudeCode {
+ $packageSpec = Get-PackageSpec
+ $toolArgs = @("tool", "install", "--force")
+
+ if (-not [string]::IsNullOrWhiteSpace($TorchBackend)) {
+ $toolArgs += @("--torch-backend", $TorchBackend)
+ }
+
+ $toolArgs += $packageSpec
+ Invoke-InstallCommand -FilePath "uv" -Arguments $toolArgs
+}
+
+if ($Help) {
+ Show-Usage
+ return
+}
+
+if ($RemainingArgs.Count -gt 0) {
+ Show-Usage
+ throw "Unknown option: $($RemainingArgs -join ' ')"
+}
+
+if ((-not [string]::IsNullOrWhiteSpace($TorchBackend)) -and (-not ($VoiceLocal -or $VoiceAll))) {
+ throw "-TorchBackend requires -VoiceLocal or -VoiceAll."
+}
+
+Write-Step "Installing or updating Claude Code"
+Assert-CommandAvailable "npm"
+Invoke-InstallCommand -FilePath "npm" -Arguments @("install", "-g", "@anthropic-ai/claude-code")
+
+Write-Step "Installing or updating uv"
+Install-OrUpdateUv
+
+Write-Step "Installing Python $PythonVersion"
+Invoke-InstallCommand -FilePath "uv" -Arguments @("python", "install", $PythonVersion)
+
+Write-Step "Installing or updating Free Claude Code"
+Install-FreeClaudeCode
+
+Write-Host ""
+Write-Host "Free Claude Code is installed. Start the proxy with: fcc-server"
diff --git a/scripts/install.sh b/scripts/install.sh
new file mode 100644
index 00000000..59f70c64
--- /dev/null
+++ b/scripts/install.sh
@@ -0,0 +1,217 @@
+#!/bin/sh
+set -eu
+
+REPO_GIT_URL="git+https://github.com/Alishahryar1/free-claude-code.git"
+PYTHON_VERSION="3.14.0"
+UV_INSTALL_URL="https://astral.sh/uv/install.sh"
+
+dry_run=0
+voice_nim=0
+voice_local=0
+voice_all=0
+torch_backend=""
+
+show_usage() {
+ cat <<'USAGE'
+Usage: install.sh [options]
+
+Installs or updates Claude Code, uv, Python 3.14.0, and Free Claude Code.
+
+Options:
+ --voice-nim Install NVIDIA NIM voice transcription support.
+ --voice-local Install local Whisper voice transcription support.
+ --voice-all Install all voice transcription backends.
+ --torch-backend VALUE Use a uv PyTorch backend, such as cu130. Requires local voice.
+ --dry-run Print commands without running them.
+ --help Show this help text.
+USAGE
+}
+
+fail() {
+ printf 'error: %s\n' "$*" >&2
+ exit 1
+}
+
+step() {
+ printf '\n==> %s\n' "$1"
+}
+
+quote_arg() {
+ case "$1" in
+ *[!A-Za-z0-9_./:@%+=,-]*|"")
+ escaped=$(printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g')
+ printf '"%s"' "$escaped"
+ ;;
+ *)
+ printf '%s' "$1"
+ ;;
+ esac
+}
+
+print_command() {
+ printf '+'
+ for arg in "$@"; do
+ printf ' '
+ quote_arg "$arg"
+ done
+ printf '\n'
+}
+
+run() {
+ print_command "$@"
+ if [ "$dry_run" -eq 0 ]; then
+ "$@"
+ fi
+}
+
+run_uv_installer() {
+ printf '+ curl -LsSf %s | sh\n' "$UV_INSTALL_URL"
+ if [ "$dry_run" -eq 0 ]; then
+ command -v curl >/dev/null 2>&1 || fail "curl is required to install uv."
+ curl -LsSf "$UV_INSTALL_URL" | sh
+ fi
+}
+
+add_path_entry() {
+ [ -n "$1" ] || return 0
+ case ":$PATH:" in
+ *":$1:"*) ;;
+ *) PATH="$1:$PATH" ;;
+ esac
+}
+
+add_uv_to_path() {
+ if [ -n "${XDG_BIN_HOME:-}" ]; then
+ add_path_entry "$XDG_BIN_HOME"
+ fi
+
+ if [ -n "${HOME:-}" ]; then
+ add_path_entry "$HOME/.local/bin"
+ add_path_entry "$HOME/.cargo/bin"
+ fi
+
+ export PATH
+}
+
+require_command() {
+ if [ "$dry_run" -eq 0 ] && ! command -v "$1" >/dev/null 2>&1; then
+ fail "$1 is required. Install it first, then rerun this installer."
+ fi
+}
+
+install_or_update_uv() {
+ add_uv_to_path
+
+ if ! command -v uv >/dev/null 2>&1; then
+ run_uv_installer
+ add_uv_to_path
+ fi
+
+ if [ "$dry_run" -eq 0 ] && ! command -v uv >/dev/null 2>&1; then
+ fail "uv was installed, but it is not available on PATH. Open a new terminal or add uv's bin directory to PATH."
+ fi
+
+ run uv self update
+}
+
+parse_args() {
+ while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --voice-nim)
+ voice_nim=1
+ ;;
+ --voice-local)
+ voice_local=1
+ ;;
+ --voice-all)
+ voice_all=1
+ ;;
+ --torch-backend)
+ shift
+ [ "$#" -gt 0 ] || fail "--torch-backend requires a value."
+ torch_backend="$1"
+ [ -n "$torch_backend" ] || fail "--torch-backend requires a non-empty value."
+ ;;
+ --torch-backend=*)
+ torch_backend="${1#*=}"
+ [ -n "$torch_backend" ] || fail "--torch-backend requires a non-empty value."
+ ;;
+ --dry-run)
+ dry_run=1
+ ;;
+ --help|-h)
+ show_usage
+ exit 0
+ ;;
+ *)
+ show_usage >&2
+ fail "unknown option: $1"
+ ;;
+ esac
+ shift
+ done
+}
+
+validate_args() {
+ include_local=$voice_local
+
+ if [ "$voice_all" -eq 1 ]; then
+ include_local=1
+ fi
+
+ if [ -n "$torch_backend" ] && [ "$include_local" -ne 1 ]; then
+ fail "--torch-backend requires --voice-local or --voice-all."
+ fi
+}
+
+package_spec() {
+ include_nim=$voice_nim
+ include_local=$voice_local
+
+ if [ "$voice_all" -eq 1 ]; then
+ include_nim=1
+ include_local=1
+ fi
+
+ if [ -n "$torch_backend" ] && [ "$include_local" -ne 1 ]; then
+ fail "--torch-backend requires --voice-local or --voice-all."
+ fi
+
+ if [ "$include_nim" -eq 1 ] && [ "$include_local" -eq 1 ]; then
+ printf 'free-claude-code[voice,voice_local] @ %s' "$REPO_GIT_URL"
+ elif [ "$include_nim" -eq 1 ]; then
+ printf 'free-claude-code[voice] @ %s' "$REPO_GIT_URL"
+ elif [ "$include_local" -eq 1 ]; then
+ printf 'free-claude-code[voice_local] @ %s' "$REPO_GIT_URL"
+ else
+ printf '%s' "$REPO_GIT_URL"
+ fi
+}
+
+install_free_claude_code() {
+ spec=$(package_spec)
+
+ if [ -n "$torch_backend" ]; then
+ run uv tool install --force --torch-backend "$torch_backend" "$spec"
+ else
+ run uv tool install --force "$spec"
+ fi
+}
+
+parse_args "$@"
+validate_args
+
+step "Installing or updating Claude Code"
+require_command npm
+run npm install -g @anthropic-ai/claude-code
+
+step "Installing or updating uv"
+install_or_update_uv
+
+step "Installing Python $PYTHON_VERSION"
+run uv python install "$PYTHON_VERSION"
+
+step "Installing or updating Free Claude Code"
+install_free_claude_code
+
+printf '\nFree Claude Code is installed. Start the proxy with: fcc-server\n'