Free Claude Code is a local proxy that sits between the Claude Code CLI (or its VS Code/JetBrains extensions) and 18 different model providers, translating requests so the client behaves exactly as it normally would. Understanding how to set it up is useful any time you want the Claude Code workflow without being locked to a single backend.
Free Claude Code intercepts every request Claude Code would normally send to Anthropic and reroutes it to a provider of your choosing, rewriting the response back into the shape Claude Code expects.
┌─────────────────────────────────────────────────────────────────┐ │ Free Claude Code Proxy │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Request Flow: │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │ │ Claude │───▶│ FCC │───▶│ Provider │───▶│ Model │ │ │ │ Code │ │ Proxy │ │ Adapter │ │ Backend │ │ │ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ │ │ │ Response Flow: │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │ │ Claude │◀───│ FCC │◀───│ Provider │◀───│ Model │ │ │ │ Code │ │ Proxy │ │ Adapter │ │ Backend │ │ │ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘
Note: because it reroutes traffic away from Anthropic's own servers, you're only talking to Anthropic's hosted Claude models if you specifically configure a provider that serves them. Keep that in mind before relying on this for anything beyond personal experimentation.
Free Claude Code resolves each request through a fixed chain before it ever leaves your machine:
# Conceptual routing order inside the proxy ROUTING = [ "Claude Code / Codex client", # sends Anthropic Messages or OpenAI Responses "FastAPI proxy (/v1/messages, /v1/responses)", # 1st: receives request "Model router", # 2nd: resolves MODEL_OPUS / MODEL_SONNET / MODEL_HAIKU / MODEL "Provider adapter", # 3rd: OpenAI-compat or Anthropic-compat transport "Upstream provider API", # 4th: NVIDIA NIM, OpenRouter, Ollama, etc. ]
Free Claude Code is organized around a few key layers:
# Conceptual shape of the proxy internals class FreeClaudeCodeProxy: def __init__(self): """ One-time setup: loads Admin UI-managed settings, provider catalog, and auth token. """ self.settings = load_settings() # config/ self.providers = load_provider_catalog() # config/provider_catalog def handle_messages(self, request): """ Handles Claude Code's /v1/messages calls. Routes to the correct provider adapter based on model tier. """ provider = self.resolve_provider(request.model) return provider.send(request) def handle_responses(self, request): """ Handles Codex's /v1/responses calls. Converts Responses payloads to Anthropic Messages internally, then shares the same router and adapters. """ converted = to_anthropic_messages(request) return self.handle_messages(converted) def resolve_provider(self, model_name): """ Maps 'opus' / 'sonnet' / 'haiku' in the model name to MODEL_OPUS / MODEL_SONNET / MODEL_HAIKU, falling back to MODEL. """ pass
Install (or update) Free Claude Code and its dependencies, including Claude Code and Codex if they're missing:
# macOS/Linux curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh
# Windows PowerShell irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" | iex
To remove only Free Claude Code later (leaving Claude Code, Codex, and uv intact):
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh
fcc-server
Uvicorn prints the bind address, and the app logs the local Admin UI URL:
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
Keep this process running for the whole session — every client request passes through it.
Open the Admin UI link from the terminal. As an example, wiring up NVIDIA NIM:
# 1. Get a key open https://build.nvidia.com/settings/api-keys # 2. In the Admin UI: # - Paste the key into NVIDIA_NIM_API_KEY # - Click Validate, then Apply
The default model is nvidia_nim/nvidia/nemotron-3-super-120b-a12b, changeable from the same screen. Other supported providers include OpenRouter, Google AI Studio (Gemini), DeepSeek, Mistral, Groq, Cerebras, Fireworks AI, Cloudflare, Z.ai, and local options like Ollama, LM Studio, and llama.cpp — each takes an API key or base URL plus a provider/model-slug.
You can also split traffic by tier so heavier requests use a stronger model:
# Admin UI fields MODEL_OPUS=nvidia_nim/moonshotai/kimi-k2.6 MODEL_SONNET=open_router/openrouter/free MODEL_HAIKU=lmstudio/qwen3.5-coder MODEL=zai/glm-5.1 # fallback for anything unmatched
fcc-claude
fcc-claude reads the current Admin UI port and auth token every time it starts, sets ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN (plus a 190k-token CLAUDE_CODE_AUTO_COMPACT_WINDOW), then launches the real claude binary — so from here it behaves exactly like a normal Claude Code session.
Install the Claude Code extension, then set:
"claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }, { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" }, { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" } ]
Reload the extension window. If a login screen appears, choosing the Anthropic Console path once is fine — the proxy still intercepts model traffic once the environment variables are active.
fcc-codex
Registers an ephemeral fcc model provider pointed at the local /v1/responses endpoint, generates a model catalog for Codex's native /model picker, and strips official OPENAI_* credentials from the child environment so traffic stays local.
In the Admin UI, under Messaging:
Messaging Platform: discord | telegram Discord Bot Token: <paste> Allowed Discord Channels: <channel IDs> Allowed Directory: /absolute/path/to/workspace
Click Validate, then Apply. Useful commands once running: /stop (cancel a task), /clear (reset a session), /stats (show session state).
# Local Whisper (CPU or CUDA) curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-local # NVIDIA NIM transcription curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh -s -- --voice-nim
Restart fcc-server afterward, then enable Voice Notes under Messaging → Voice in the Admin UI.
# The Admin UI is loopback-only by design — don't expose port 8082 # to the network without adding your own auth layer in front of it.
# Route cheap/local models to Haiku-tier traffic, # save stronger remote models for Opus-tier reasoning-heavy calls MODEL_HAIKU=ollama/llama3.1:8b MODEL_OPUS=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
# Re-run the same install command to update in place curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" | sh
# Inspect before piping to sh curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" -o install.sh less install.sh
If you're running from a source checkout rather than the installer, use the project's own CI sequence:
git clone https://github.com/Alishahryar1/free-claude-code.git cd free-claude-code uv run uvicorn server:app --host 0.0.0.0 --port 8082 # Full local check (format, lint, type-check, tests) ./scripts/ci.sh
# Individual checks uv run ruff format uv run ruff check --fix uv run ty check uv run pytest -v --tb=short
Free Claude Code is a clean example of protocol translation applied to a real developer workflow. Key takeaways:
MODEL_OPUS/MODEL_SONNET/MODEL_HAIKU let you mix cheap and strong models in the same session.With these steps, you can run the familiar Claude Code interface against whichever model backend fits your budget, latency, or privacy needs.