\# 🤖 Free Claude Code

Use Claude Code CLI, Codex CLI, their VS Code extensions, JetBrains ACP, or chat bots 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 Claude Code or Codex 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](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/pic.png)

_Claude Code running through the Free Claude Code proxy._

![Codex CLI in action through Free Claude Code](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/codex.png)

_Codex CLI using the local FCC Responses provider._

![Claude Code model picker showing gateway models](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/cc-model-picker.png)

_Claude Code native `/model` picker with FCC gateway models._

![Codex model picker showing generated FCC model catalog](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/codex-model-picker.png)

_Codex native `/model` picker with the generated FCC catalog._

\## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=Alishahryar1/free-claude-code&type=Date)](https://star-history.com/#Alishahryar1/free-claude-code&Date)

\## What You Get

\- Launch Claude Code with \`fcc-claude\` or Codex with \`fcc-codex\`.
\- Switch among 24 cloud and local providers from the Admin UI.
\- Use the native Claude Code and Codex \`/model\` pickers.
\- Route Opus, Sonnet, Haiku, and fallback traffic to different models.
\- Keep streaming, tool use, and reasoning support 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

The installer provisions Free Claude Code, uv, and Python 3.14. It also installs Claude Code and Codex when they are missing; install \[Node.js\](https://nodejs.org/) first so \`npm\` is available for those agents.

macOS/Linux:

\`\`\`bash
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" \| sh
\`\`\`

Windows PowerShell:

\`\`\`powershell
irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1" \| iex
\`\`\`

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. The startup log shows the Admin UI address:

\`\`\`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 select another model.
5\. Click \*\*Validate\*\*, then \*\*Apply\*\*.

![Local admin UI for proxy settings](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/admin-page.png)

\### 4\. Run Your Coding Agent

Claude Code:

\`\`\`bash
fcc-claude
\`\`\`

Codex:

\`\`\`bash
fcc-codex
\`\`\`

Both launchers use the current Admin UI settings. Type \`/model\` inside either agent to choose from the models FCC exposes. Normal CLI arguments still work, for example:

\`\`\`bash
fcc-codex exec "hello"
\`\`\`

\## Choose A Provider

Enter the listed setting in the Admin UI, set \`MODEL\` to a provider-prefixed model ID, then 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\` \|
\| \[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\` \|
\| \[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\](https://platform.moonshot.ai/console/api-keys) \| \`KIMI\_API\_KEY\` \| \`kimi/kimi-k2.5\` \|
\| \[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\` \|
\| \[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.
\- OpenCode Zen and OpenCode Go share \`OPENCODE\_API\_KEY\` but use different model prefixes.
\- Cloudflare requires both its API token and account ID.
\- 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. Set \`MODEL\_OPUS\`, \`MODEL\_SONNET\`, or \`MODEL\_HAIKU\` to override individual Claude Code tiers; leave a tier blank to inherit \`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\`.

\## Connect Your Client

For terminal use, start \`fcc-server\`, then prefer \`fcc-claude\` or \`fcc-codex\`. 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). In VS Code settings, edit \`claudeCode.environmentVariables\`:

\`\`\`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" }\
\]
\`\`\`

Match the port and authentication token to the Admin UI, then reload the extension. If prompted to log in, choose the Anthropic Console path once; FCC still handles model traffic.

**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"
env\_key = "FCC\_CODEX\_API\_KEY"
wire\_api = "responses"
\`\`\`

Store the Admin UI authentication token in \`~/.codex/auth.json\` or its Windows equivalent:

\`\`\`json
{
 "FCC\_CODEX\_API\_KEY": "freecc"
}
\`\`\`

Match \`model\`, the port, and the token to the Admin UI, then restart VS Code. For WSL-backed Codex, edit the files 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"
}
\`\`\`

Match the port and token to the Admin UI, then restart the IDE.

\## Optional Integrations

Configure integrations from \*\*Admin UI → Messaging\*\*, then click \*\*Validate\*\* and \*\*Apply\*\*.

![Admin UI Messaging view with bot and voice settings](https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/assets/admin-messaging.png)

**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.

Bot commands: standalone \`/stop\` cancels all work, standalone \`/clear\` resets all
FCC state and removes every tracked message in that chat—including user prompts,
voice notes, FCC replies, Telegram's online notice, and the clear command itself.
\`/stats\` shows session state. Reply with \`/stop\` to cancel only that request while
other queued requests continue. Reply with \`/clear\` to delete the selected message
and its literal platform reply subtree while preserving its ancestors and siblings.
A successful stop updates the affected task status instead of posting a second
confirmation message. A no-op, or a global stop whose affected statuses are in
another chat, still replies explicitly.

**Voice notes**

Re-run the installer with the voice backend you need.

macOS/Linux:

\`\`\`bash
\# NVIDIA NIM transcription
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" \| sh -s -- --voice-nim

\# Local Whisper on CPU or CUDA
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" \| sh -s -- --voice-local

\# Both backends
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" \| sh -s -- --voice-all

\# Local Whisper with the CUDA 13.0 PyTorch backend
curl -fsSL "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.sh?raw=1" \| sh -s -- --voice-local --torch-backend cu130
\`\`\`

Windows PowerShell:

\`\`\`powershell
\# NVIDIA NIM transcription
& (\[scriptblock\]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceNim

\# Local Whisper on CPU or CUDA
& (\[scriptblock\]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceLocal

\# Both backends
& (\[scriptblock\]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -VoiceAll

\# Local Whisper with the CUDA 13.0 PyTorch backend
& (\[scriptblock\]::Create((irm "https://github.com/Alishahryar1/free-claude-code/blob/main/scripts/install.ps1?raw=1"))) -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 uninstall script removes the FCC uv tool and always deletes \`~/.fcc/\`; it does not remove uv, Python, Claude Code, or Codex.

macOS/Linux:

\`\`\`bash
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" \| sh
\`\`\`

Windows PowerShell:

\`\`\`powershell
irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1" \| iex
\`\`\`

\## 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.