Use Claude Code for free with claude-free — full setup (NVIDIA NIM + Kimi-K2)

# Use Claude Code for free with `claude-free`

A drop-in `claude-free` command that runs Claude Code through a local proxy → NVIDIA NIM's free tier → Kimi-K2. Use it when your Anthropic / Claude Code quota is exhausted. **Zero impact on your existing `claude` setup** — both commands coexist.

Tested on macOS (Apple Silicon) with Claude Code v2.1.112.

---

## What you'll have when this is done

- A new shell command `claude-free` that works exactly like `claude` (interactive UI, `--print`, `--model`, all flags pass through).
- Routes through a local FastAPI proxy on `127.0.0.1:8082` → NVIDIA NIM → `moonshotai/kimi-k2-instruct`.
- **Free tier**: NVIDIA NIM gives ~40 req/min and ~5,000 free credits on signup. Plenty for steady coding.
- Your normal `claude` command and `~/.claude/` config are **untouched** — env vars are scoped to the wrapper only.

---

## Prereqs (the human must do this part, agent cannot)

The user needs **one** thing the agent can't grab itself:

1. **NVIDIA NIM API key** (free, ~1 min):
   - Go to https://build.nvidia.com/settings/api-keys
   - Sign in (Google/GitHub works)
   - Click **Generate API Key** → copy the `nvapi-...` value

If the user hasn't done this, **stop and ask them for the key** before proceeding. Do NOT continue without it.

The user should already have:
- macOS or Linux (Windows works too but path conventions below differ)
- `claude` (Claude Code CLI) — install with `npm i -g @anthropic-ai/claude-code` if missing
- `uv` (Python package manager) — install with `curl -LsSf https://astral.sh/uv/install.sh | sh` if missing
- `git`, `curl`

---

## Setup (agent runs these)

### 1. Clone the proxy to a persistent location

```bash
mkdir -p ~/.local/share
rm -rf ~/.local/share/claude-free
git clone --depth 1 https://github.com/Alishahryar1/free-claude-code.git ~/.local/share/claude-free
```

> Use `~/.local/share/claude-free` (persists across reboots), **not** `/tmp` (wiped on reboot).

### 2. Install Python 3.14 + dependencies via uv

```bash
cd ~/.local/share/claude-free
uv python install 3.14
uv sync
```

Takes ~30s. Resolves into an isolated `.venv` inside the dir — does not touch system Python.

### 3. Write the `.env` config

Replace `YOUR_NVIDIA_KEY_HERE` with the actual key from prereqs.

```bash
cat > ~/.local/share/claude-free/.env <<'EOF'
NVIDIA_NIM_API_KEY=YOUR_NVIDIA_KEY_HERE
MODEL=nvidia_nim/moonshotai/kimi-k2-instruct
ANTHROPIC_AUTH_TOKEN=freecc
EOF
```

> ⚠️ **Do NOT use the README's default `nvidia_nim/z-ai/glm4.7`.** It's listed on NIM's catalog but hangs upstream — requests never return. We've verified `moonshotai/kimi-k2-instruct` works reliably and is the strongest coding-tuned model on the free tier. `meta/llama-3.3-70b-instruct` is a working fallback.

> `ANTHROPIC_AUTH_TOKEN=freecc` is a local-only secret. Claude Code sends it to the proxy; the proxy verifies it. Doesn't go to NVIDIA or Anthropic. Pick any string.

### 4. Create the `claude-free` wrapper

```bash
mkdir -p ~/.local/bin
cat > ~/.local/bin/claude-free <<'EOF'
#!/usr/bin/env bash
# claude-free: launch Claude Code routed through local NVIDIA NIM proxy.
# Use when your Anthropic / Claude Code quota is exhausted.
# Does NOT touch your normal `claude` setup — env vars are inline only.

set -e

PROXY_DIR="$HOME/.local/share/claude-free"
PORT=8082
LOG="$PROXY_DIR/proxy.log"
PIDFILE="$PROXY_DIR/proxy.pid"

start_proxy() {
  cd "$PROXY_DIR"
  nohup uv run uvicorn server:app --host 127.0.0.1 --port "$PORT" >> "$LOG" 2>&1 &
  echo $! > "$PIDFILE"
  for i in {1..30}; do
    if curl -s -m 1 "http://127.0.0.1:$PORT/v1/models" -H "x-api-key: freecc" >/dev/null 2>&1; then
      return 0
    fi
    sleep 0.5
  done
  echo "claude-free: proxy failed to start. See $LOG" >&2
  exit 1
}

if ! curl -s -m 1 "http://127.0.0.1:$PORT/v1/models" -H "x-api-key: freecc" >/dev/null 2>&1; then
  echo "claude-free: starting proxy on :$PORT..." >&2
  start_proxy
fi

export ANTHROPIC_AUTH_TOKEN=freecc
export ANTHROPIC_BASE_URL="http://127.0.0.1:$PORT"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

exec claude "$@"
EOF
chmod +x ~/.local/bin/claude-free
```

### 5. Confirm `~/.local/bin` is on PATH

```bash
echo "$PATH" | tr ':' '\n' | grep -q "$HOME/.local/bin" && echo "PATH ok" || echo "ADD ~/.local/bin TO PATH"
```

If not present, append to `~/.zshrc` (or `~/.bashrc`):

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Then `source ~/.zshrc` (or open a new terminal).

---

## Verify it works

### Smoke test (one-shot, 5 sec)

```bash
claude-free --print --model claude-3-5-sonnet-20241022 "Reply with exactly: CLAUDE_FREE_OK"
```

Expected output: `CLAUDE_FREE_OK` (Kimi may add minor formatting).

If you see `claude-free: starting proxy on :8082...` first, that's normal — it's auto-starting the proxy.

### Confirm routing actually goes through the proxy (not Anthropic)

```bash
grep -c "POST /v1/messages" ~/.local/share/claude-free/proxy.log
```

Should be ≥ 1 and increment with every `claude-free` request.

**Definitive proof** — kill the proxy and watch wrapper restart it:

```bash
pkill -f "uvicorn server:app"
claude-free --print "test"
# You'll see "claude-free: starting proxy on :8082..." again. If Claude Code were
# bypassing the proxy, this restart would be unnecessary.
```

### Try it interactively

```bash
claude-free
```

Type something, get a response. **Note**: Claude Code's UI may still show your old "Sonnet 4.6 · Atlys" label in the header. That label is cached locally and doesn't reflect actual routing — proven by the proxy log. Cosmetic only.

---

## When to use which command

| Command | When |
|---|---|
| `claude` | Real work. Opus / Sonnet on your paid Anthropic / Claude Team account. |
| `claude-free` | Quota exhausted. Free Kimi-K2 via NIM. ~80% as good for typical coding tasks; not as strong for deep refactors. |

You can swap freely — they're independent processes.

---

## Caveats (be honest about these)

1. **Quality is Kimi-K2, not Opus.** Strong at coding and tool use, but not Anthropic-level on hard reasoning. Use as fallback, not replacement.
2. **Free tier limits.** ~40 req/min (one Claude Code turn = 5–15 requests, so steady use is fine). NVIDIA gives ~5k free credits on signup; budget refreshes vary.
3. **Identity sycophancy.** If you ask Kimi "what model are you?" it may say "Claude Sonnet" because Claude Code's system prompt tells it that. The model is actually Kimi — proven by the `model` field in proxy responses (`moonshotai/kimi-k2-instruct`). Cosmetic, not functional.
4. **Proxy sees your prompts.** It's localhost-only and the source is open ([Alishahryar1/free-claude-code](https://github.com/Alishahryar1/free-claude-code)), but technically every prompt passes through it on its way to NVIDIA. No raw logging is enabled by default. Don't run this proxy on a shared machine.
5. **Single-author project.** The proxy went 0 → 23k stars in days. Code is clean (FastAPI, Pydantic, pytest, MIT) and architecture is sane, but it's maintained by one person. Audit yourself if paranoid.
6. **Some NIM models hang.** `z-ai/glm4.7` (the README's default), `deepseek-v4-pro`, and `qwen/qwen3-coder-480b` were unreachable in our testing. Stick to `moonshotai/kimi-k2-instruct` or `meta/llama-3.3-70b-instruct`.

---

## Switching models

Edit `~/.local/share/claude-free/.env` → change the `MODEL=` line → restart:

```bash
pkill -f "uvicorn server:app"
claude-free --print "test"   # auto-restarts proxy with new model
```

Verified working on NIM free tier:
- `nvidia_nim/moonshotai/kimi-k2-instruct` (best coding, recommended)
- `nvidia_nim/meta/llama-3.3-70b-instruct` (honest about identity, decent)

---

## Stop / uninstall

**Stop the proxy** (frees port 8082):
```bash
pkill -f "uvicorn server:app"
```

**Uninstall everything**:
```bash
pkill -f "uvicorn server:app"
rm -rf ~/.local/share/claude-free ~/.local/bin/claude-free
```

Nothing else to clean. Your normal `claude` setup is untouched throughout.

---

## Troubleshooting

**`claude-free: proxy failed to start`**
→ Check `~/.local/share/claude-free/proxy.log`. Most common cause: port 8082 already taken. Fix: kill whatever's on it (`lsof -i :8082`) or change `PORT` in the wrapper script.

**Requests hang forever after `message_start`**
→ The configured `MODEL=` is on NIM's catalog but unreachable. Switch to `moonshotai/kimi-k2-instruct`. See caveat #6.

**`claude-free: command not found`**
→ `~/.local/bin` isn't on your PATH. See setup step 5.

**`401 Unauthorized` from proxy**
→ `ANTHROPIC_AUTH_TOKEN` mismatch. The wrapper exports `freecc`; `.env` must also have `ANTHROPIC_AUTH_TOKEN=freecc`.

**Claude Code UI shows wrong account name in header**
→ Cosmetic only. Trust the proxy log (`grep "POST /v1/messages" ~/.local/share/claude-free/proxy.log`) for ground truth.

---

## What this is built on (credits)

- [Alishahryar1/free-claude-code](https://github.com/Alishahryar1/free-claude-code) — the proxy that translates Anthropic Messages API → OpenAI Chat Completions for NIM. MIT licensed.
- [NVIDIA NIM](https://build.nvidia.com/) — free-tier inference for 130+ models.
- [Moonshot Kimi-K2](https://moonshotai.com/) — the actual model doing the coding.

The `claude-free` wrapper, the verified-working model selection, the env layout, and the safety scoping are this npad's contribution.