# free-claude-code **Repository Path**: gary0755/free-claude-code ## Basic Information - **Project Name**: free-claude-code - **Description**: Use claude-code for free in the terminal, VSCode extension or discord like OpenClaw (voice supported) - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-25 - **Last Updated**: 2026-06-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# πŸ€– Free Claude Code Use Claude Code CLI, VS Code, JetBrains ACP, or chat bots through your own Anthropic-compatible proxy. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) [![Python 3.14](https://img.shields.io/badge/python-3.14-3776ab.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge)](https://github.com/astral-sh/uv) [![Tested with Pytest](https://img.shields.io/badge/testing-Pytest-00c0ff.svg?style=for-the-badge)](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml) [![Type checking: Ty](https://img.shields.io/badge/type%20checking-ty-ffcc00.svg?style=for-the-badge)](https://pypi.org/project/ty/) [![Code style: Ruff](https://img.shields.io/badge/code%20formatting-ruff-f5a623.svg?style=for-the-badge)](https://github.com/astral-sh/ruff) [![Logging: Loguru](https://img.shields.io/badge/logging-loguru-4ecdc4.svg?style=for-the-badge)](https://github.com/Delgan/loguru) Free Claude Code routes Anthropic Messages API traffic from Claude Code to any provider. It keeps Claude Code's client-side protocol stable while letting you choose free, paid, or local models. [Quick Start](#quick-start) Β· [Providers](#choose-a-provider) Β· [Clients](#connect-claude-code) Β· [Integrations](#optional-integrations) Β· [Development](#development)
Free Claude Code in action
## Star History
Star History Chart
## What You Get - Drop-in proxy for Claude Code's Anthropic API calls. - Eleven provider backends: NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, and Z.ai. - Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers. - 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)). - Streaming, tool use, reasoning/thinking block handling, and local request optimizations. - Optional Discord or Telegram bot wrapper for remote coding sessions. - Optional Usage through the VSCode extension. - Optional voice-note transcription through local Whisper or NVIDIA NIM. - Local **Admin UI** at `/admin` to edit supported proxy settings, validate changes, and check providers (loopback access only). ## Quick Start ### 1. Install the latest version of [Claude Code](https://code.claude.com/docs/en/overview) ```bash npm install -g @anthropic-ai/claude-code ``` ### 2. Install Runtime Requirements Install the latest version of [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.14. macOS/Linux: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh uv self update uv python install 3.14 ``` Windows PowerShell: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" uv self update uv python install 3.14 ``` ### 3. Install The Proxy ```bash uv tool install --force git+https://github.com/Alishahryar1/free-claude-code.git ``` Use the same command to update to the latest version. ### 4. Start The Proxy ```bash fcc-server ``` After startup, Uvicorn prints the proxy bind address and the app logs the admin URL: ```text INFO: Admin UI: http://127.0.0.1:8082/admin (local-only) ``` Many terminals make these clickable. Use your configured `PORT` if it is not `8082`. ### 5. Open The Admin UI And Configure NVIDIA NIM Open the **Admin UI** URL from the terminal output. Need an NVIDIA NIM API key? Use the **[NVIDIA NIM provider](#nvidia-nim-provider)** section below, then scroll back up here.
Local admin UI for proxy settings
Paste your NVIDIA NIM API key into `NVIDIA_NIM_API_KEY`, then click **Validate** and **Apply**. The default model is already set to `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`. You can change it later from the same Admin UI. ### 6. Run Claude Code ```bash fcc-claude ``` `fcc-claude` reads the current configured port and auth token each time it starts, sets the Claude Code environment variables (including a 190k-token `CLAUDE_CODE_AUTO_COMPACT_WINDOW` for auto-compaction), and then launches the real `claude` command. ## Choose A Provider Pick one provider, enter its key or local URL in the Admin UI, and set `MODEL` to a provider-prefixed model slug. `MODEL` is the fallback. `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` can override routing for Claude Code's model tiers. ### 1. [NVIDIA NIM](https://build.nvidia.com/) Get a key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys). In the Admin UI, paste it into `NVIDIA_NIM_API_KEY`. The default `MODEL` is `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`. Popular examples: - `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` - `nvidia_nim/z-ai/glm5.1` - `nvidia_nim/moonshotai/kimi-k2.5` - `nvidia_nim/minimaxai/minimax-m2.5` Browse models at [build.nvidia.com](https://build.nvidia.com/explore/discover). ### 2. [Kimi](https://platform.moonshot.ai/) Get a key at [platform.moonshot.ai/console/api-keys](https://platform.moonshot.ai/console/api-keys). In the Admin UI, paste it into `KIMI_API_KEY`, then set `MODEL` to a Kimi slug such as `kimi/kimi-k2.5`. Browse models at [platform.moonshot.ai](https://platform.moonshot.ai). ### 3. [Wafer](https://wafer.ai/) Get a key from [wafer.ai](https://wafer.ai). In the Admin UI, paste it into `WAFER_API_KEY`, then set `MODEL` to a Wafer Pass model such as `wafer/DeepSeek-V4-Pro`. Popular examples: - `wafer/DeepSeek-V4-Pro` - `wafer/MiniMax-M2.7` - `wafer/Qwen3.5-397B-A17B` - `wafer/GLM-5.1` This provider uses Wafer's Anthropic-compatible endpoint at `https://pass.wafer.ai/v1/messages`. ### 4. [OpenRouter](https://openrouter.ai/) Get a key at [openrouter.ai/keys](https://openrouter.ai/keys). In the Admin UI, paste it into `OPENROUTER_API_KEY`, then set `MODEL` to an OpenRouter slug such as `open_router/stepfun/step-3.5-flash:free`. Browse [all models](https://openrouter.ai/models) or [free models](https://openrouter.ai/collections/free-models). ### 5. [DeepSeek](https://platform.deepseek.com/) Get a key at [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys). In the Admin UI, paste it into `DEEPSEEK_API_KEY`, then set `MODEL` to a DeepSeek slug such as `deepseek/deepseek-chat`. This provider uses DeepSeek's Anthropic-compatible endpoint, not the OpenAI chat-completions endpoint. ### 6. [LM Studio](https://lmstudio.ai/) Start LM Studio's local server and load a model. In the Admin UI, keep or update `LM_STUDIO_BASE_URL`, then set `MODEL` to the model identifier shown by LM Studio, prefixed with `lmstudio/`. Prefer models with tool-use support for Claude Code workflows. ### 7. [llama.cpp](https://github.com/ggml-org/llama.cpp) Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests. In the Admin UI, keep or update `LLAMACPP_BASE_URL`, then set `MODEL` to the local model slug, prefixed with `llamacpp/`. For local coding models, context size matters. If llama.cpp returns HTTP 400 for normal Claude Code requests, increase `--ctx-size` and verify the model/server build supports the requested features. ### 8. [Ollama](https://ollama.com/) Run Ollama and pull a model: ```bash ollama pull llama3.1 ollama serve ``` In the Admin UI, keep or update `OLLAMA_BASE_URL`, then set `MODEL` to the same tag shown by `ollama list`, prefixed with `ollama/`. `OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. Example model slugs include `ollama/llama3.1` and `ollama/llama3.1:8b`. ### 9. [OpenCode Zen](https://opencode.ai/) Get an API key at [opencode.ai/auth](https://opencode.ai/auth). In the Admin UI, paste it into `OPENCODE_API_KEY`, then set `MODEL` to an OpenCode Zen model slug such as `opencode/gpt-5.3-codex`. The same `OPENCODE_API_KEY` powers **OpenCode Go** (below); use `opencode_go/` slugs there. OpenCode Zen is a curated model gateway that provides access to models from Anthropic, OpenAI, Google, DeepSeek, and more through a single API key and OpenAI-compatible endpoint at `https://opencode.ai/zen/v1`. Popular examples: - `opencode/gpt-5.3-codex` - `opencode/claude-sonnet-4` - `opencode/deepseek-v4-flash-free` (free) - `opencode/gemini-3-flash` - `opencode/big-pickle` (free) - `opencode/glm-5.1` Browse available models at [opencode.ai](https://opencode.ai). ### 10. [OpenCode Go](https://opencode.ai/) Get an API key at [opencode.ai/auth](https://opencode.ai/auth) (same as OpenCode Zen). In the Admin UI, use `OPENCODE_API_KEY`, then set `MODEL` to an OpenCode Go model slug such as `opencode_go/minimax-m2.7`. OpenCode Go is a subscription gateway with its own curated catalog and OpenAI-compatible endpoint at `https://opencode.ai/zen/go/v1`. It shares the **same OpenCode API key** as Zen; only the slug prefix (`opencode_go/` vs `opencode/`) and upstream path differ. Popular examples: - `opencode_go/minimax-m2.7` Browse available models at [opencode.ai](https://opencode.ai). ### 11. [Z.ai](https://z.ai/) Get an API key at [Z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list). In the Admin UI, paste it into `ZAI_API_KEY`, then set `MODEL` to a Z.ai model slug such as `zai/glm-5.1`. Z.ai provides GLM models through the OpenAI-compatible Coding Plan endpoint at `https://api.z.ai/api/coding/paas/v4`. Popular examples: - `zai/glm-5.1` - `zai/glm-5-turbo` Browse models at [Z.ai](https://z.ai). ### 12. Mix Providers By Model Tier Each model tier can use a different provider by setting `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` in the Admin UI. Leave a tier blank to inherit `MODEL`. For example, you can route Opus to `nvidia_nim/moonshotai/kimi-k2.5`, Sonnet to `open_router/deepseek/deepseek-r1-0528:free`, Haiku to `lmstudio/unsloth/GLM-4.7-Flash-GGUF`, and keep the fallback `MODEL` on `zai/glm-5.1`. ## Connect Claude Code ### 1. Claude Code CLI For terminal use, prefer the installed launcher: ```bash fcc-claude ``` Keep `fcc-server` running while you work. The Admin UI manages proxy config, restarts the server when runtime settings change, and `fcc-claude` reads the current Admin UI-managed port and auth token every time it starts. It also sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to `190000` for auto-compaction. ### 2. VS Code Extension Open Settings, search for `claude-code.environmentVariables`, choose **Edit in settings.json**, and add: ```json "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. If the extension shows a login screen, choose the Anthropic Console path once; the local proxy still handles model traffic after the environment variables are active. ### 3. JetBrains ACP Edit the installed Claude ACP config: - Windows: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json` - Linux/macOS: `~/.jetbrains/acp.json` Set the environment for `acp.registry.claude-acp`: ```json "env": { "ANTHROPIC_BASE_URL": "http://localhost:8082", "ANTHROPIC_AUTH_TOKEN": "freecc", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000" } ``` Restart the IDE after changing the file. ### 4. Model Picker
Claude Code model picker showing gateway models
## Optional Integrations For every integration below, change **managed proxy settings** only in the **Admin UI** at `/admin`: edit fields, click **Validate**, then **Apply**. The footer shows where the managed config is stored; this README does not walk through editing that file by hand. ### 1. Discord And Telegram Bots The bot wrapper runs Claude Code sessions remotely, streams progress, supports reply-based conversation branches, and can stop or clear tasks. **Discord** 1. Create the bot in the [Discord Developer Portal](https://discord.com/developers/applications). 2. Enable **Message Content Intent**. 3. Invite the bot with read, send, and message history permissions. 4. Copy the bot token and the numeric channel ID (or IDs) where the bot should respond. **Telegram** 1. Create a bot with [@BotFather](https://t.me/BotFather) and copy the bot token. 2. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot) so only you can use the bot. **Configure in the Admin UI** 1. With `fcc-server` running, open the **Admin UI** URL from the terminal output. 2. In the sidebar, choose **Messaging**. 3. Set **Messaging Platform** to **discord** or **telegram**. 4. For Discord, paste **Discord Bot Token** and **Allowed Discord Channels**. For Telegram, paste **Telegram Bot Token** and **Allowed Telegram User ID**. 5. Set **Allowed Directory** to an absolute path on the machine running the proxyβ€”the workspace root the bot may use. 6. Click **Validate**, then **Apply**. Restart the server if the UI says one is required.
Admin UI Messaging view with bot and voice settings

Admin UI β†’ Messaging (platform, bots, and Voice)

**Useful commands** - `/stop` cancels a task; reply to a task message to stop only that branch. - `/clear` resets sessions; reply to clear one branch. - `/stats` shows session state. ### 2. Voice Notes Voice notes work on Discord and Telegram after you extend your [proxy install](#3-install-the-proxy) with the matching optional extras. Re-run `uv tool install --force` with the extras you need (same Git URL as Quick Start): ```bash # NVIDIA NIM transcription (Riva gRPC) uv tool install --force "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git" # Local Whisper (CPU or CUDA) uv tool install --force "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git" # Both backends uv tool install --force "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git" ``` For **cuda** local Whisper, add `--torch-backend cu130` to the `voice_local` install command. Restart `fcc-server` after reinstalling. In the **Admin UI**, open **Messaging** and scroll to **Voice**. Turn on **Voice Notes**, choose **Whisper Device** (`cpu`, `cuda`, or `nvidia_nim`), set **Whisper Model**, and enter **Hugging Face Token** when your setup needs it. For **nvidia_nim** transcription, install the `voice` extra and set **NVIDIA NIM API Key** on the **Providers** view. The screenshot above shows the **Voice** block in the same view. ## How It Works
Free Claude Code request flow architecture
Diagram source: [`assets/how-it-works.mmd`](assets/how-it-works.mmd). Important pieces: - FastAPI exposes Anthropic-compatible routes such as `/v1/messages`, `/v1/messages/count_tokens`, and `/v1/models`. - Model routing resolves the Claude model name to `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, or `MODEL`. - NIM, OpenCode Zen, OpenCode Go, Z.ai use OpenAI chat streaming translated into Anthropic SSE. - Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports. - The proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape Claude Code expects. - Request optimizations answer trivial Claude Code probes locally to save latency and quota. ## Development ### 1. Project Structure ```text free-claude-code/ β”œβ”€β”€ server.py # ASGI entry point β”œβ”€β”€ api/ # FastAPI routes, service layer, routing, optimizations β”œβ”€β”€ core/ # Shared Anthropic protocol helpers and SSE utilities β”œβ”€β”€ providers/ # Provider transports, registry, rate limiting β”œβ”€β”€ messaging/ # Discord/Telegram adapters, sessions, voice β”œβ”€β”€ cli/ # Package entry points and Claude process management β”œβ”€β”€ config/ # Settings, provider catalog, logging └── tests/ # Unit and contract tests ``` ### 2. Run From Source Use this path if you are developing or want to run directly from a checkout: ```bash 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 ``` ### 3. Commands ```bash uv run ruff format uv run ruff check uv run ty check uv run pytest ``` Run them in that order before pushing. CI enforces the same checks. ### 4. Package Scripts `pyproject.toml` installs: - `fcc-server`: starts the proxy with configured host and port. - `fcc-init`: optional advanced scaffold for `~/.fcc/.env`; prefer the **Admin UI** for normal configuration. - `fcc-claude`: launches Claude Code with the configured local proxy URL, auth token, model discovery flag, and a 190k `CLAUDE_CODE_AUTO_COMPACT_WINDOW` for auto-compaction. - `free-claude-code`: compatibility alias for `fcc-server`. ### 5. Extending - Add OpenAI-compatible providers by extending `OpenAIChatTransport`. - Add Anthropic Messages providers by extending `AnthropicMessagesTransport`. - Register provider metadata in `config.provider_catalog` and factory wiring in `providers.registry`. - Add messaging platforms by implementing the `MessagingPlatform` interface in `messaging/`. ## Contributing - [`.env.example`](.env.example) lists env key names as a read-only reference for contributors; use the **Admin UI** to change managed proxy settings. - Report bugs and feature requests in [Issues](https://github.com/Alishahryar1/free-claude-code/issues). - Keep changes small and covered by focused tests. - Do not open Docker integration PRs. - Do not open README change PRs just open an issue for it. - Run the full check sequence before opening a pull request. - The syntax `except X, Y` is brought back in python 3.14 final version (not in 3.14 alpha). Keep in mind before opening PRs. ## License MIT License. See [LICENSE](LICENSE) for details.