Yash030/claude-code-proxy
2
1---2title: Claude Code Proxy3emoji: 🤖4colorFrom: blue5colorTo: purple6sdk: docker7sdk_version: "3.14"8python_version: "3.14"9app_file: server.py10pinned: false11---12 13<div align="center">14 15# 🤖 Free Claude Code16 17**Use Claude Code with free NVIDIA NIM models through a lightweight proxy.**18 19[](https://opensource.org/licenses/MIT)20[](https://www.python.org/downloads/)21[](https://github.com/astral-sh/uv)22[](https://github.com/astral-sh/ruff)23 24</div>25 26## The Problem27 28Claude Code costs $100+/month for API access. This project lets you run it using **free NVIDIA NIM models** instead.29 30## The Solution31 32A FastAPI proxy that translates Claude Code's Anthropic API calls to NVIDIA NIM's OpenAI-compatible endpoint. Zero code changes needed in Claude Code.33 34```35┌─────────────────┐ Anthropic API ┌──────────────────┐36│ Claude Code │ ──────────────────────▶ │ Free Claude │37│ (Official) │ │ Code │38│ │ ◀──────────────────────── │ Proxy │39└─────────────────┘ SSE Streaming │ (:8082) │40 └────────┬─────────┘41 │42 OpenAI Chat API43 │44 ▼45 ┌──────────────────┐46 │ NVIDIA NIM │47 │ (Free Models) │48 └──────────────────┘49```50 51## Features52 53- **Drop-in replacement** for Claude Code's Anthropic API54- **7 free NVIDIA NIM models** available via auto-routing55- **Automatic failover** - switches to next model if one hits rate limit56- **Multi-model support** - use different models for different tasks57- **Local optimizations** - fast-path for common probes (saves API calls)58- **Streaming** - real-time response with SSE59- **Tool support** - Claude Code tools work with NIM models60- **Thinking blocks** - reasoning support where models support it61- **Discord/Telegram bots** - remote Claude Code sessions62- **Voice notes** - transcribe voice messages with Whisper63 64## Quick Start (Cloud - No Setup)65 66The easiest way to use this project is on **HuggingFace Spaces** (free tier available).67 68### 1. Deploy to HuggingFace Spaces69 70<a target="_blank" href="https://huggingface.co/new-space?template=Yash030/claude-code-proxy">71 <img src="https://huggingface.co/datasets/huggingface/badges/raw/main/deploy-to-spaces-lg.svg" alt="Deploy to HuggingFace Spaces"/>72</a>73 74Or manually:751. Go to [huggingface.co/spaces/Yash030/claude-code-proxy](https://huggingface.co/spaces/Yash030/claude-code-proxy)762. Duplicate the space773. Set your secrets in the Space settings:78 - `NVIDIA_NIM_API_KEY` - Your NVIDIA API key79 - `ANTHROPIC_AUTH_TOKEN` - Your auth token (any secret)80 81### 2. Get NVIDIA API Key82 83Get a free key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).84 85### 3. Connect Claude Code86 87```bash88# Use your HuggingFace Space URL (ends with .hf.space)89export ANTHROPIC_AUTH_TOKEN="your-secret-token"90export ANTHROPIC_BASE_URL="https://your-space-name.hf.space"91claude92```93 94That's it! Claude Code will use free NVIDIA NIM models.95 96## Quick Start (Local)97 98### 1. Install Requirements99 100```bash101# Install Claude Code102curl -LsSf https://download.anthropic.com/install.sh | sh103 104# Install uv (fast Python package manager)105curl -LsSf https://astral.sh/uv/install.sh | sh106uv python install 3.14107```108 109### 2. Clone and Configure110 111```bash112git clone https://github.com/Yashwant00CR7/claude-code-nvidia.git113cd claude-code-nvidia114cp .env.example .env115```116 117Edit `.env`:118```dotenv119NVIDIA_NIM_API_KEY="nvapi-your-key"120ANTHROPIC_AUTH_TOKEN="freecc"121MODEL="nvidia_nim/z-ai/glm4.7"122```123 124### 3. Start Proxy125 126```bash127uv sync128uv run uvicorn server:app --host 0.0.0.0 --port 8082129```130 131### 4. Run Claude Code132 133```bash134export ANTHROPIC_AUTH_TOKEN="freecc"135export ANTHROPIC_BASE_URL="http://localhost:8082"136claude137```138 139## Available Models140 141The proxy automatically routes to these models in order:142 143| Model | Best For | Speed |144|-------|----------|-------|145| `qwen3-coder-480b` | Code generation | Fast |146| `glm4.7` | General purpose | Fast |147| `step-3.5-flash` | Fast responses | Very Fast |148| `mistral-large-3` | Reasoning | Medium |149| `dracarys-llama-3.1-70b` | Complex tasks | Medium |150| `seed-oss-36b` | Balanced | Fast |151| `mistral-nemotron` | Thinking tasks | Medium |152 153## How Auto-Routing Works154 155When you use `auto` model, the proxy:156 1571. **Tries models in order** of speed/reliability1582. **Skips rate-limited models** - pre-flight check before each request1593. **Fast failover** - if one model times out, immediately tries next1604. **No API waste** - common probes handled locally161 162```163Request: "Write a function"164 ↓165Check if model 1 is rate-limited? → Yes → Skip166Check if model 2 is rate-limited? → No → Try167 ↓168Model 2 responds? → Yes → Stream response169Model 2 timeout? → Try model 3 → Success!170```171 172## Environment Variables173 174### Required175```dotenv176NVIDIA_NIM_API_KEY="nvapi-your-key" # From build.nvidia.com177ANTHROPIC_AUTH_TOKEN="your-secret" # Any secret you choose178```179 180### Optional181```dotenv182MODEL="nvidia_nim/z-ai/glm4.7" # Default model183MODEL_OPUS="nvidia_nim/qwen/qwen3-..." # Model for Opus requests184MODEL_SONNET="nvidia_nim/z-ai/glm4.7" # Model for Sonnet requests185MODEL_HAIKU="nvidia_nim/z-ai/glm4.7" # Model for Haiku requests186 187# Auto-routing order (comma-separated)188AUTO_MODEL_PRIORITY="nvidia_nim/qwen/...,nvidia_nim/z-ai/..."189 190# Thinking support191ENABLE_MODEL_THINKING=true # Enable reasoning blocks192```193 194## IDE Integration195 196### VS Code Extension197 198Add to `.vscode/settings.json`:199```json200{201 "claudeCode.environmentVariables": [202 { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }204 ]205}206```207 208### JetBrains ACP209 210Edit `~/.jetbrains/acp.json`:211```json212{213 "env": {214 "ANTHROPIC_BASE_URL": "http://localhost:8082",215 "ANTHROPIC_AUTH_TOKEN": "freecc"216 }217}218```219 220### Remote/Ssh221 222For remote development, deploy to HuggingFace Spaces and use:223```bash224export ANTHROPIC_BASE_URL="https://your-space.hf.space"225```226 227## Deployment Options228 229### HuggingFace Spaces (Recommended for Cloud)230 231**Free tier includes:**232- 2 vCPU233- Community support234- Automatic HTTPS235- Git-based deployment236 237**Setup:**2381. Fork [the space](https://huggingface.co/spaces/Yash030/claude-code-proxy)2392. Add `NVIDIA_NIM_API_KEY` to Space secrets2403. Access at `https://your-space.hf.space`241 242### Railway (Easy Deploy)243 2441. Connect GitHub repo2452. Set environment variables2463. Deploy with auto-scaling247 248### Render (Free Tier)249 2501. Create Web Service2512. Connect GitHub2523. Set build command: `uv sync`2534. Set start command: `uv run uvicorn server:app --host 0.0.0.0 --port $PORT`254 255### Fly.io (Global Edge)256 257```bash258fly launch259fly secrets set NVIDIA_NIM_API_KEY="nvapi-..."260fly deploy261```262 263### Local/Docker264 265```bash266docker build -t free-claude-code .267docker run -p 8082:8082 \268 -e NVIDIA_NIM_API_KEY="nvapi-..." \269 -e ANTHROPIC_AUTH_TOKEN="freecc" \270 free-claude-code271```272 273## Architecture274 275```276api/277├── routes.py # FastAPI endpoints278├── services.py # Request handling & failover279├── model_router.py # Model resolution280├── detection.py # Request type detection281└── optimization_handlers.py # Fast-path responses282 283core/284├── anthropic/ # SSE, token counting, tool parsing285└── task_detector.py # Task capability detection286 287providers/288├── openai_compat.py # Base OpenAI transport289├── nvidia_nim/ # NVIDIA NIM provider290└── rate_limit.py # Rate limiting291 292messaging/293├── discord.py # Discord bot wrapper294└── telegram.py # Telegram bot wrapper295```296 297## Troubleshooting298 299### "undefined ... input_tokens" error300- Update to latest version: `git pull`301- Check `ANTHROPIC_BASE_URL` doesn't end with `/v1`302 303### Provider disconnects during streaming304- Reduce `PROVIDER_MAX_CONCURRENCY`305- Increase `HTTP_READ_TIMEOUT`306- Check NVIDIA NIM status at [status.nvidia.com](https://status.nvidia.com)307 308### Model not responding309- Check your NVIDIA API key is valid310- Verify rate limits haven't been hit311- Try a different model312 313### VS Code extension shows login314- Reload the extension after setting env vars315- Confirm environment variables are set correctly316 317## Contributing318 3191. Fork the repo3202. Create a feature branch3213. Run checks: `uv run ruff format && uv run ruff check && uv run ty check`3224. Submit PR323 324## License325 326MIT License - See [LICENSE](LICENSE)327 328## Links329 330- [GitHub](https://github.com/Yashwant00CR7/claude-code-nvidia)331- [HuggingFace Space](https://huggingface.co/spaces/Yash030/claude-code-proxy)332- [NVIDIA NIM](https://build.nvidia.com)333- [Claude Code](https://github.com/anthropics/claude-code)334