<div align="center">

🤖 Free Claude Code

Use Claude Code CLI & VSCode for free. No Anthropic API key required.

A lightweight proxy that routes Claude Code's Anthropic API calls to NVIDIA NIM (40 req/min free), OpenRouter (hundreds of models), DeepSeek (direct API), LM Studio (fully local), or llama.cpp (local with Anthropic endpoints).

Quick Start · Providers · Discord Bot · Configuration · Development · Contributing

---

</div> <div align="center"> <img src="pic.png" alt="Free Claude Code in action" width="700"> <p><em>Claude Code running via NVIDIA NIM, completely free</em></p> </div>

Features

| Feature | Description | | -------------------------- | ----------------------------------------------------------------------------------------------- | | Zero Cost | 40 req/min free on NVIDIA NIM. Free models on OpenRouter. Fully local with LM Studio | | Drop-in Replacement | Set 2 env vars. No modifications to Claude Code CLI or VSCode extension needed | | 5 Providers | NVIDIA NIM, OpenRouter, DeepSeek, LM Studio (local), llama.cpp (llama-server) | | Per-Model Mapping | Route Opus / Sonnet / Haiku to different models and providers. Mix providers freely | | Thinking Token Support | Parses <think> tags and reasoning_content into native Claude thinking blocks | | Heuristic Tool Parser | Models outputting tool calls as text are auto-parsed into structured tool use | | Request Optimization | 5 categories of trivial API calls intercepted locally, saving quota and latency | | Smart Rate Limiting | Proactive rolling-window throttle + reactive 429 exponential backoff + optional concurrency cap | | Discord / Telegram Bot | Remote autonomous coding with tree-based threading, session persistence, and live progress | | Subagent Control | Task tool interception forces run_in_background=False. No runaway subagents | | Extensible | Clean BaseProvider and MessagingPlatform ABCs. Add new providers or platforms easily |

Quick Start

Prerequisites

1. Get an API key (or use LM Studio / llama.cpp locally):
   • NVIDIA NIM: build.nvidia.com/settings/api-keys
   • OpenRouter: openrouter.ai/keys
   • DeepSeek: platform.deepseek.com/api_keys
   • LM Studio: No API key needed. Run locally with LM Studio
   • llama.cpp: No API key needed. Run llama-server locally.
2. Install Claude Code

Install uv

# Install uv (required to run the project)
pip install uv

If uv is already installed, run uv self update to get the latest version.

Clone & Configure

git clone https://github.com/codeaashu/free-claude-code.git
cd free-claude-code
cp .env.example .env

Choose your provider and edit .env:

<details> <summary><b>NVIDIA NIM</b> (40 req/min free, recommended)</summary>

NVIDIA_NIM_API_KEY="nvap…[redacted]"

MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
MODEL="nvidia_nim/z-ai/glm4.7"                     # fallback

# Global switch for provider reasoning requests and Claude thinking blocks.
ENABLE_THINKING=true

</details> <details> <summary><b>OpenRouter</b> (hundreds of models)</summary>

OPENROUTER_API_KEY="sk-o…[redacted]"

MODEL_OPUS="open_router/deepseek/deepseek-r1-0528:free"
MODEL_SONNET="open_router/openai/gpt-oss-120b:free"
MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"
MODEL="open_router/stepfun/step-3.5-flash:free"     # fallback

</details> <details> <summary><b>DeepSeek</b> (direct API)</summary>

DEEPSEEK_API_KEY="your-deepseek-key-here"

MODEL_OPUS="deepseek/deepseek-reasoner"
MODEL_SONNET="deepseek/deepseek-chat"
MODEL_HAIKU="deepseek/deepseek-chat"
MODEL="deepseek/deepseek-chat"                      # fallback

</details> <details> <summary><b>LM Studio</b> (fully local, no API key)</summary>

MODEL_OPUS="lmstudio/unsloth/MiniMax-M2.5-GGUF"
MODEL_SONNET="lmstudio/unsloth/Qwen3.5-35B-A3B-GGUF"
MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
MODEL="lmstudio/unsloth/GLM-4.7-Flash-GGUF"         # fallback

</details> <details> <summary><b>llama.cpp</b> (fully local, no API key)</summary>

LLAMACPP_BASE_URL="http://localhost:8080/v1"

MODEL_OPUS="llamacpp/local-model"
MODEL_SONNET="llamacpp/local-model"
MODEL_HAIKU="llamacpp/local-model"
MODEL="llamacpp/local-model"

</details> <details> <summary><b>Mix providers</b></summary>

Each MODEL_* variable can use a different provider. MODEL is the fallback for unrecognized Claude models.

NVIDIA_NIM_API_KEY="nvap…[redacted]"
OPENROUTER_API_KEY="sk-o…[redacted]"

MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"
MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free"
MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
MODEL="nvidia_nim/z-ai/glm4.7"                      # fallback

</details>

Migration: NIM_ENABLE_THINKING was removed in this release. Rename it to ENABLE_THINKING.

<details> <summary><b>Optional Authentication</b> (restrict access to your proxy)</summary>

Set ANTHROPIC_AUTH_TOKEN in .env to require clients to authenticate:

ANTHROPIC_AUTH_TOKEN="your-secret-token-here"

How it works:

• If ANTHROPIC_AUTH_TOKEN is empty (default), no authentication is required (backward compatible)
• If set, clients must provide the same token via the ANTHROPIC_AUTH_TOKEN header
• The claude-pick script automatically reads the token from .env if configured

Example usage:

# With authentication
ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \
ANTHROPIC_BASE_URL="http://localhost:8082" claude

# claude-pick automatically uses the configured token
claude-pick

Use this feature if:

• Running the proxy on a public network
• Sharing the server with others but restricting access
• Wanting an additional layer of security

</details>

Run It

Terminal 1: Start the proxy server:

uv run uvicorn server:app --host 0.0.0.0 --port 8082

Terminal 2: Run Claude Code:

Point ANTHROPIC_BASE_URL at the proxy root URL, not http://localhost:8082/v1.

Powershell

$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude

Bash

ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude

That's it! Claude Code now uses your configured provider for free.

<details> <summary><b>VSCode Extension Setup</b></summary>

1. Start the proxy server (same as above).
2. Open Settings (Ctrl + ,) and search for claude-code.environmentVariables.
3. Click Edit in settings.json and add:

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
]

4. Reload extensions.
5. If you see the login screen: Click Anthropic Console, then authorize. The extension will start working. You may be redirected to buy credits in the browser; ignore it — the extension already works.

To switch back to Anthropic models, comment out the added block and reload extensions.

</details> <details> <summary><b>IntelliJ Extension Setup</b></summary>

1. Open the configuration file:

   • Windows: C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
   • Linux/macOS: ~/.jetbrains/acp.json

2. Inside acp.registry.claude-acp, change:

   "env": {}
   

   to

   "env": {
   "ANTHROPIC_AUTH_TOKEN": "freecc",
   "ANTHROPIC_BASE_URL": "http://localhost:8082"
   }
   

3. Start the proxy server

4. Restart IDE

</details> <details> <summary><b>Multi-Model Support (Model Picker)</b></summary>

claude-pick is an interactive model selector that lets you choose any model from your active provider each time you launch Claude, without editing MODEL in .env.

https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645

1. Install fzf:

brew install fzf        # macOS/Linux

2. Add the alias to ~/.zshrc or ~/.bashrc:

alias claude-pick="/absolute/path/to/free-claude-code/claude-pick"

Then reload your shell (source ~/.zshrc or source ~/.bashrc) and run claude-pick.

Or use a fixed model alias (no picker needed):

alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude'

</details>

Install as a Package (no clone needed)

uv tool install git+https://github.com/codeaashu/free-claude-code.git
fcc-init        # creates ~/.config/free-claude-code/.env from the built-in template

Edit ~/.config/free-claude-code/.env with your API keys and model names, then:

free-claude-code    # starts the server

To update: uv tool upgrade free-claude-code

---

How It Works

┌─────────────────┐        ┌──────────────────────┐        ┌──────────────────┐
│  Claude Code    │───────>│  Free Claude Code    │───────>│  LLM Provider    │
│  CLI / VSCode   │<───────│  Proxy (:8082)       │<───────│  NIM / OR / LMS  │
└─────────────────┘        └──────────────────────┘        └──────────────────┘
   Anthropic API                                             Native Anthropic
   format (SSE)                                             or OpenAI chat SSE

• Transparent proxy: Claude Code sends standard Anthropic API requests; the proxy forwards them to your configured provider
• Per-model routing: Opus / Sonnet / Haiku requests resolve to their model-specific backend, with MODEL as fallback
• Request optimization: 5 categories of trivial requests (quota probes, title generation, prefix detection, suggestions, filepath extraction) are intercepted and responded to locally without using API quota
• Format handling: OpenRouter, LM Studio, and llama.cpp use native Anthropic Messages endpoints; NIM and DeepSeek use shared OpenAI chat translation
• Thinking tokens: <think> tags and reasoning_content fields are converted into native Claude thinking blocks when ENABLE_THINKING=true

The proxy also exposes Claude-compatible probe routes: GET /v1/models, POST /v1/messages, `POST /v1/messag