🟡 Intermediate ⚙️ Type: API Proxy / CLI Coding Agent 💸 Free & Open Source (MIT) ⭐ 33,600+ GitHub Stars
What is free-claude-code?
free-claude-code is a clever open-source local proxy server that allows you to use Anthropic’s official Claude Code CLI or VS Code extension completely for free. It tricks the official software into routing its intelligence through alternative, free, or local AI providers instead of charging your Anthropic credit card.
Normally, Claude Code is hardcoded to talk directly to Anthropic’s expensive servers. This tool sits quietly on your computer as a middleman. When Claude Code tries to send a prompt, the proxy intercepts it, translates the formatting, and sends it to a free API (like NVIDIA NIM) or a local offline model (like Ollama or LM Studio). When the alternative AI responds, the proxy translates it back into Anthropic’s exact streaming format.
To Claude Code, it looks like it is talking to Claude Opus or Sonnet. To your wallet, the cost is zero.
Who is it for?
- Budget-conscious developers who want the premium experience of the official Claude Code CLI without burning through expensive Anthropic API credits.
- Privacy advocates and enterprise devs who cannot send proprietary company code to cloud servers and want to route Claude Code through 100% offline local models via Ollama.
- AI tinkers who want to experiment with hybrid routing (e.g., using a massive local model for basic scaffolding and DeepSeek or OpenRouter for complex reasoning).
- Remote workers who want to trigger autonomous coding sessions directly from their phone using the built-in Discord/Telegram bot integrations.
What makes it special?
- Request Optimization (Quota Saver) — Claude Code generates a lot of “waste” API calls in the background just for counting tokens, generating UI titles, or validating file paths. This proxy intercepts those trivial calls and answers them locally, drastically saving your free API rate limits.
- Flawless Protocol Translation — It is not just a simple URL redirect. It actively translates complex tool calls, chunked token streaming, and “ reasoning tags mid-stream so the client doesn’t crash.
- NVIDIA NIM Native — It works perfectly out-of-the-box with NVIDIA NIM’s generous free tier (which offers thousands of free monthly credits) and defaults to powerful open-weights coding models.
- Subagent Control — Automatically blocks Claude Code from launching runaway infinite-loop subagents, preventing you from accidentally burning your rate limits.
- Universal Compatibility — It works seamlessly with the terminal CLI, the official VS Code extension, and JetBrains IDEs.
Requirements before you start
You need a few basic developer tools installed on your machine to run the proxy:
- Python &
uv— The server runs on Python. The fastest way to run it is by installing the uv package manager. - Claude Code — You must have the official tool installed globally via npm (
npm install -g @anthropic-ai/claude-code). - An Alternative API Key — We highly recommend creating a free account at build.nvidia.com to get an NVIDIA NIM API key. Alternatively, you can use OpenRouter or run LM Studio locally.
- Git — Required to clone the proxy repository.
Step-by-step installation
Step 1 — Clone the repository
Open your terminal and download the proxy software:
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .envStep 2 — Configure your free API Key
Open the newly created .env file in any text editor. Add your NVIDIA NIM API key and set your target model (Moonshot’s Kimi or Qwen are highly recommended for coding tasks):
NVIDIA_NIM_API_KEY="nvapi-your-key-here"
MODEL="nvidia_nim/moonshotai/kimi-k2.5"
ENABLE_MODEL_THINKING=trueStep 3 — Start the Proxy Server
Use uv to spin up the local FastAPI server. You must leave this terminal window running in the background while you code:
uv run uvicorn server:app --host 127.0.0.1 --port 8082You will see a success message indicating the proxy is listening on port 8082.
Step 4 — Launch Claude Code (Terminal)
Open a second terminal window. You need to tell the official Claude CLI to route its traffic to your new local proxy instead of Anthropic’s servers. Run this command:
ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://127.0.0.1:8082" claudeClaude Code will launch normally, but all of its complex tool requests are now being processed entirely for free!
Step 5 (Optional) — Configure the VS Code Extension
If you prefer using the VS Code extension over the terminal, open VS Code settings (Ctrl + ,), search for claude-code.environmentVariables, and edit your settings.json to include:
"claude-code.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "http://127.0.0.1:8082" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
]Reload VS Code. If it asks you to log in, just click the standard login path once—the environment variables will override the network traffic automatically.
Common errors and fixes
| Error | What it means | How to fix it |
|---|---|---|
429 Too Many Requests | You have hit the free tier rate limit on NVIDIA NIM (usually 40 requests per minute). | The proxy has an automatic exponential backoff feature built-in, so simply wait 15 seconds. If you hit this constantly, switch your backend provider to LM Studio to run locally. |
| Claude Code gets stuck in an infinite loop or “hangs” | The specific third-party model you selected is struggling to output the strict tool-calling JSON that Claude Code requires. | Not all models are smart enough to drive Claude. Avoid the default GLM models if they hang. Use highly capable coding alternatives like kimi-k2.5, Qwen3.5-Coder, or Llama-3.3-70b-Instruct. |
Connection Refused when launching Claude | The official CLI cannot find your local proxy. | Ensure your terminal window running the uvicorn server is still active and that you correctly typed the ANTHROPIC_BASE_URL environment variable. |
Free vs Paid comparison
| Feature | free-claude-code (via Proxy) | Official Claude Code (Native) |
|---|---|---|
| Cost | $0 (Using local or free-tier APIs) | Pay-per-token API billing |
| Intelligence / Reliability | 🟡 Moderate — depends entirely on the alternative model you choose | 🟢 Extremely High — native Claude 3.7 Sonnet tool use |
| Offline Privacy | ✅ Yes — if paired with Ollama/LM Studio | ❌ No — all code is sent to Anthropic servers |
| Setup Difficulty | ⚠️ Requires running a background python proxy server | 🟢 Plug and play |
Bottom line: If you are working on personal side projects, exploring the workflow, or need strict offline privacy, this proxy is a massive money saver. However, because Claude Code was engineered specifically for Claude 3.7’s unique reasoning style, using alternative models will occasionally result in tool-calling bugs or slower logic loops. For professional production environments where your time equals money, paying for the native API is still the better route.
Alternatives — 3 similar tools
1. Aider
The gold standard of open-source terminal coding assistants. Aider natively supports hundreds of models (including DeepSeek, OpenAI, and local Ollama) right out of the box without needing a proxy. It edits files directly and manages your git commits automatically.
2. OpenHands (Formerly OpenDevin)
A full browser-based, open-source AI software engineer. Instead of just a terminal CLI, it provides a massive sandbox workspace where the AI can write code, run bash commands, and browse the web autonomously. It natively supports OpenRouter and local backends.
🔗 github.com/All-Hands-AI/OpenHands
3. Cline (VS Code Extension)
A highly popular open-source coding agent that lives entirely inside VS Code. It features a built-in provider dropdown, allowing you to seamlessly switch between Anthropic, DeepSeek, OpenRouter, or LM Studio without touching command-line proxies.
🚀 Want more free AI tools like this?
We find, test, and write setup guides for the best free and open-source AI tools — so you don’t have to dig through GitHub yourself.Browse Free AI Tools at globalaiforce.com/shop →
📸 Follow us for daily AI tool tips and tutorials: instagram.com/globalaiforce