free-claude-code
CLI ToolAlishahryar1/free-claude-code
Free proxy to use Claude Code with alternative AI providers like NVIDIA or DeepSeek.
Overview
A local proxy server that routes Claude Code's API calls to free or local AI providers such as NVIDIA NIM, OpenRouter, DeepSeek, and Ollama. It allows using Claude Code without an Anthropic subscription by translating the protocol to compatible backends. Supports streaming, tool use, and model routing.
README Preview
\n\n# 🤖 Free Claude Code\n\nUse Claude Code CLI, VS Code, JetBrains ACP, or chat bots through your own Anthropic-compatible proxy.\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/astral-sh/uv)\n[](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)\n[](https://pypi.org/project/ty/)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/Delgan/loguru)\n\nFree Claude Code routes Anthropic Messages API traffic from Claude Code to NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, or Ollama. It keeps Claude Code's client-side protocol stable while letting you choose free, paid, or local models.\n\n[Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-claude-code) · [Troubleshooting](#troubleshooting) · [Development](#development)\n\n\n\n\n \n\n\n## Star History\n\n\n \n \n \n \n \n \n \n\n\n## What You Get\n\n- Drop-in proxy for Claude Code's Anthropic API calls.\n- Six provider backends: NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama.\n- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers.\n- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (Claude Code must opt in to Gateway model discovery; see [Model Picker](#model-picker)).\n- Streaming, tool use, reasoning/thinking block handling, and local request optimizations.\n- Optional Discord or Telegram bot wrapper for remote coding sessions.\n- Optional voice-note transcription through local Whisper or NVIDIA NIM.\n\n## Quick Start\n\n### 1. Install Requirements\n\nInstall [Claude Code](https://github.com/anthropics/claude-code), then install `uv` and Python 3.14.\n\nmacOS/Linux:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv self update\nuv python install 3.14\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/u
FAQ (4)
TroubleshootingHow to fix free-claude-code proxy 422 error when Claude Code sends system messages?
Update the Message model in api/models/anthropic.py (line 95) to allow the "system" role: role: Literal["user", "assistant", "system"]. After editing, restart the proxy. Note: This is a local patch that will be overwritten on update; for a permanent fix, the source repository must be updated.
TroubleshootingWhy did all models suddenly stop working in Free Claude Code (FCC) and how do I fix it?
This affects FCC version 6.16.15, which still points to the retired NVIDIA Super endpoint, causing every model request to fail. Reinstalling or rotating API keys will not help. Fix: run fcc-update to upgrade to 6.16.16 or later — this version automatically migrates the NVIDIA Super selection to the new Ultra endpoint — then restart FCC. If it still fails after updating, open the FCC settings page and correct any wrong model mappings.
TroubleshootingWhy is the Free Claude Code menu bar (tray) icon missing on macOS, and how do I fix it?
This is a known issue when launching FCC from ~/Applications/Free Claude Code.app: the bundle's executable is a shell script that execs a Python interpreter outside the bundle, and macOS will not display a status item for that launcher pattern (it persists regardless of LSUIElement or ad-hoc codesign -s -). The server still runs and http://localhost:8082/admin works, but you lose the Open Admin / Restart Server / Quit tray menu. Workaround: kill the running instance with pkill -f fcc-desktop, then start FCC from a terminal by running fcc-desktop directly — the menu bar icon appears normally. Note that clicking the .app again does nothing because the second instance finds desktop.lock held and silently exits. A permanent fix requires a compiled launcher binary or a bundle that bundles/links its own Python executable.
TroubleshootingHow to fix "There's an issue with the selected model. It may not exist or you may not have access to it" error in Claude Code?
This error means Claude Code's request for the selected model (e.g., claude-opus-5) is rejected by the backend — the server logs show repeated 404 Not Found responses for POST /v1/messages?beta=true, meaning no route/handler exists for that model. Workaround: run /model inside Claude Code and switch to a model your provider or proxy actually supports, then retry the prompt. If you route Claude Code through a proxy such as FCC, verify that your FCC version registers an endpoint for the selected model, restart the server after changing config, and run fcc doctor to confirm provider configuration.