# free-claude-code **Repository Path**: lr998/free-claude-code ## Basic Information - **Project Name**: free-claude-code - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-18 - **Last Updated**: 2026-07-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# 🤖 Free Claude Code Use Claude Code, Codex, Pi, or their IDE extensions through your own provider-backed 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) Run your coding agents with free, paid, or local models. Choose and validate providers from one local Admin UI. [Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-your-client) · [Integrations](#optional-integrations) · [Manage](#manage-your-installation)
Free Claude Code in action

Claude Code running through the Free Claude Code proxy.

Codex CLI in action through Free Claude Code

Codex CLI using the local FCC Responses provider.

Claude Code model picker showing gateway models

Claude Code native /model picker with FCC gateway models.

Codex model picker showing generated FCC model catalog

Codex native /model picker with the generated FCC catalog.

## What You Get - Launch Claude Code with `fcc-claude`, Codex with `fcc-codex`, or Pi with `fcc-pi`. - Switch among 25 cloud and local providers from the Admin UI. - Use each coding agent's native model picker. - Route Fable, Opus, Sonnet, Haiku, and fallback traffic to different models. - Keep streaming, tool use, reasoning, and image input across compatible models. - Connect Claude Code and Codex in VS Code or Claude Code through JetBrains ACP. - Optionally run Claude Code sessions through Discord or Telegram with voice-note transcription. - Protect the local proxy with optional token authentication. ## Quick Start ### 1. Install Or Update macOS/Linux: ```bash curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh ``` Windows PowerShell: ```powershell & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) ``` Re-run the same command whenever you want to update. You can review the installers before running them: [install.sh](scripts/install.sh) and [install.ps1](scripts/install.ps1). ### 2. Start The Server ```bash fcc-server ``` To print the installed Free Claude Code version without starting the server, run `fcc-server --version`. Keep this process running. By default, the Admin UI opens in your browser once the server is healthy. Its address is always shown in the startup log: ```text INFO: Admin UI: http://127.0.0.1:8082/admin (local-only) ``` Use the port shown in your terminal if it differs from `8082`. ### 3. Configure NVIDIA NIM 1. Create an API key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys). 2. Open the Admin UI URL from the server log. 3. Paste the key into `NVIDIA_NIM_API_KEY`. 4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or search the model dropdown and select another model. 5. Click **Validate**, then **Apply**.
Local admin UI for proxy settings
### 4. Run Your Coding Agent Claude Code: ```bash fcc-claude ``` Codex: ```bash fcc-codex ``` Pi: ```bash fcc-pi ``` All three launchers use the current Admin UI settings. Use the agent's model picker to choose from the models FCC exposes. Normal CLI arguments still work, for example: ```bash fcc-codex exec "hello" ``` `fcc-pi` registers FCC only for that Pi process; your existing Pi settings, sessions, credentials, and extensions remain unchanged. ## Choose A Provider Enter the listed setting in the Admin UI, open **Model Config**, then search the `MODEL` dropdown and select a model. FCC constructs each slug as `/`; free-text entry remains available when a provider cannot list a model. Click **Validate** and **Apply**. Provider names link to their key, model, or setup pages. | Provider | Admin UI setting | Example `MODEL` | | --- | --- | --- | | [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` | | [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` | | [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` | | [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` | | [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` | | [Mistral La Plateforme](https://console.mistral.ai/) | `MISTRAL_API_KEY` | `mistral/devstral-small-latest` | | [Mistral Codestral](https://console.mistral.ai/) | `CODESTRAL_API_KEY` | `mistral_codestral/codestral-latest` | | [OpenCode Zen](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode/gpt-5.3-codex` | | [OpenCode Go](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode_go/minimax-m2.7` | | [Vercel AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers) | `AI_GATEWAY_API_KEY` | `vercel/openai/gpt-5.5` | | [Amazon Bedrock](https://console.aws.amazon.com/bedrock/) | `AWS_BEARER_TOKEN_BEDROCK` | `bedrock/openai.gpt-oss-120b` | | [Hugging Face Inference Providers](https://huggingface.co/settings/tokens) | `HUGGINGFACE_API_KEY` | `huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest` | | [Cohere](https://dashboard.cohere.com/api-keys) | `COHERE_API_KEY` | `cohere/command-a-plus-05-2026` | | [GitHub Models](https://github.com/marketplace?type=models) | `GITHUB_MODELS_TOKEN` | `github_models/openai/gpt-4.1` | | [Wafer](https://wafer.ai/) | `WAFER_API_KEY` | `wafer/DeepSeek-V4-Pro` | | [Kimi API](https://platform.moonshot.ai/console/api-keys) | `KIMI_API_KEY` | `kimi/kimi-k2.5` | | [Kimi Code](https://www.kimi.com/code/console) | `KIMI_CODE_API_KEY` | `kimi_code/k3` | | [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` | | [Cerebras Inference](https://cloud.cerebras.ai/) | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b` | | [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` | | [SambaNova](https://cloud.sambanova.ai/apis) | `SAMBANOVA_API_KEY` | `sambanova/Meta-Llama-3.3-70B-Instruct` | | [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` | | [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` | `cloudflare/@cf/moonshotai/kimi-k2.6` | | [Z.ai](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` | | [Ollama Cloud](https://ollama.com/settings/keys) | `OLLAMA_API_KEY` | `ollama_cloud/qwen3-coder:480b` | | [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/` | | [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/` | | [Ollama](https://ollama.com/) | `OLLAMA_BASE_URL` | `ollama/` | Important provider notes: - Mistral Codestral uses a separate key from Mistral La Plateforme. - Kimi Code subscription keys use `kimi_code/`; Kimi API credit keys use `kimi/`. Kimi Code plans are for personal interactive coding-agent use under [Kimi's community guidelines](https://www.kimi.com/code/docs/en/kimi-code/community-guidelines.html). - OpenCode Zen and OpenCode Go share `OPENCODE_API_KEY` but use different model prefixes. - Amazon Bedrock uses its Mantle OpenAI-compatible endpoint. Set `BEDROCK_BASE_URL` to the endpoint for the same region as the API key and select one of the models returned by FCC's model picker. - Vertex AI uses Google Application Default Credentials instead of an API key. Locally, run `gcloud auth application-default login` once; service-account files and attached service accounts also work. Set `VERTEX_PROJECT_ID`, and optionally change `VERTEX_LOCATION` from its `global` default. FCC refreshes expiring access tokens automatically. - Cloudflare requires both its API token and account ID. - Ollama Cloud connects directly to `ollama.com`; use the exact model IDs shown by FCC's model picker. Local Ollama remains available through the separate `ollama/` prefix. - Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.
Local provider setup ### LM Studio Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the `lmstudio/` prefix. The default URL is `http://localhost:1234/v1`. ### llama.cpp Start `llama-server` with its OpenAI-compatible Chat Completions API and enough context for the model. Use the local model ID with the `llamacpp/` prefix. `LLAMACPP_BASE_URL` defaults to `http://localhost:8080/v1`; FCC accepts either the server root or an explicit `/v1` suffix. ### Ollama ```bash ollama pull llama3.1 ollama serve ``` Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL` defaults to `http://localhost:11434`; FCC accepts either the root URL or an explicit `/v1` suffix.
### Optional Model-Tier Routing `MODEL` is the fallback for every request. Select a model for `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override an individual Claude Code tier; select **None** to use `MODEL`. For example, route Opus to `nvidia_nim/moonshotai/kimi-k2.6`, Sonnet to `open_router/openrouter/free`, Haiku to `lmstudio/qwen3.5-coder`, and keep `MODEL` on `zai/glm-5.2`. ### Reasoning Control Open **Admin UI → Model Config → Reasoning** to choose how FCC handles client reasoning controls. The default **From client** option preserves reasoning effort sent by Claude Code, Codex, or Pi; when the client sends no control, the provider keeps its own default. You can instead select **Off**, **Low**, **Medium**, **High**, **X-High**, or **Max**. Fable, Opus, Sonnet, and Haiku each have the same choices plus **Inherit**, which uses the root policy. Providers with named effort receive those names; numeric-budget providers map **Low=512**, **Medium=1,024**, **High=2,048**, **X-High=4,096**, and **Max=8,192** reasoning tokens; boolean providers receive on or off. Unsupported controls safely remain provider-defined. ## Connect Your Client For terminal use, start `fcc-server`, then run `fcc-claude`, `fcc-codex`, or `fcc-pi`. Use the guides below for editor integrations.
Claude Code in VS Code Install the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). Open VS Code's user settings as JSON and add: ```json "claudeCode.disableLoginPrompt": true, "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" }, { "name": "DISABLE_AUTOUPDATER", "value": "1" }, { "name": "DISABLE_FEEDBACK_COMMAND", "value": "1" }, { "name": "DISABLE_ERROR_REPORTING", "value": "1" }, { "name": "DISABLE_TELEMETRY", "value": "1" } ] ``` Match the port and authentication token to the Admin UI, then reload the extension.
Codex in VS Code Install the [Codex extension](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt). Create or edit `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows): ```toml model_provider = "fcc" model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b" [model_providers.fcc] name = "Free Claude Code" base_url = "http://127.0.0.1:8082/v1" http_headers = { Authorization = "Bearer freecc" } wire_api = "responses" ``` Match `model`, the port, and bearer token to the Admin UI, then restart VS Code. For WSL-backed Codex, edit the file inside WSL.
Claude Code in JetBrains ACP Edit the installed Claude ACP configuration: - 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", "DISABLE_AUTOUPDATER": "1", "DISABLE_FEEDBACK_COMMAND": "1", "DISABLE_ERROR_REPORTING": "1", "DISABLE_TELEMETRY": "1" } ``` Match the port and token to the Admin UI, then restart the IDE.
Claude Code still asks you to log in If Claude Code asks you to log in after you configure the FCC URL and token, open its state file: - Windows: `%USERPROFILE%\.claude.json` - macOS/Linux/WSL: `~/.claude.json` Merge this property into the existing JSON without removing its other fields: ```json "hasCompletedOnboarding": true ``` If the file does not exist, create it with a complete JSON object: ```json { "hasCompletedOnboarding": true } ``` Restart Claude Code or the IDE after saving the file.
## Optional Integrations Configure integrations from **Admin UI → Messaging**, then click **Validate** and **Apply**.
Admin UI Messaging view with bot and voice settings
Discord bot 1. Create a bot in the [Discord Developer Portal](https://discord.com/developers/applications). 2. Enable **Message Content Intent** and invite it with read, send, message-history, and **Manage Messages** permissions so `/clear` can remove user prompts. 3. Set **Messaging Platform** to **discord**. 4. Enter **Discord Bot Token**, **Allowed Discord Channels**, and an absolute **Allowed Directory**. 5. Apply the settings and restart the server if requested.
Telegram bot 1. Create a bot with [@BotFather](https://t.me/BotFather). 2. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot). In groups, grant the bot permission to delete messages. 3. Set **Messaging Platform** to **telegram**. 4. Enter **Telegram Bot Token**, **Allowed Telegram User ID**, and an absolute **Allowed Directory**. 5. Apply the settings and restart the server if requested.
### Messaging commands | Usage | Behavior | | --- | --- | | `/stats` | Show session state. | | Standalone `/stop` | Cancel all work. | | Reply with `/stop` | Cancel only the selected request while other queued requests continue. | | Standalone `/clear` | Reset all FCC state and remove every tracked message in that chat, including user prompts, voice notes, FCC replies, Telegram's online notice, and the clear command itself. | | Reply with `/clear` | Delete the selected message and its literal platform reply subtree while preserving its ancestors and siblings. |
Voice notes Re-run the installer with the voice backend you need. macOS/Linux: ```bash # NVIDIA NIM transcription curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-nim # Local Whisper on CPU or CUDA curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local # Both backends curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-all # Local Whisper with the CUDA 13.0 PyTorch backend curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local --torch-backend cu130 ``` Windows PowerShell: ```powershell # NVIDIA NIM transcription & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceNim # Local Whisper on CPU or CUDA & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal # Both backends & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceAll # Local Whisper with the CUDA 13.0 PyTorch backend & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal -TorchBackend cu130 ``` Restart `fcc-server`. In **Admin UI → Messaging → Voice**, enable voice notes, select `cpu`, `cuda`, or `nvidia_nim`, and choose the Whisper model. Local gated models need `HUGGINGFACE_API_KEY`; NVIDIA NIM transcription needs `NVIDIA_NIM_API_KEY`.
## Manage Your Installation ### Update Re-run the matching command from [Install Or Update](#install). ### Uninstall Stop every running FCC command first. The uninstaller removes the FCC uv tool, verifies every FCC command is gone, and then deletes `~/.fcc/`. It leaves uv, Python, Claude Code, Codex, Pi, and shared PATH entries intact. macOS/Linux: ```bash curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh ``` Windows PowerShell: ```powershell & ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1"))) ``` ## Project Links - [Report bugs or request features](https://github.com/Alishahryar1/free-claude-code/issues) - [Architecture and extension guide](ARCHITECTURE.md) - [Contributing guide](CONTRIBUTING.md) ## License MIT License. See [LICENSE](LICENSE) for details.