🤖 Free Claude Code

Use Claude Code CLI, Codex CLI, their VS Code extensions, JetBrains ACP, or chat bots through your own provider-backed proxy.

Run Claude Code or Codex with free, paid, or local models. Choose and validate providers from one local Admin UI.

Quick Start · Providers · Clients · Integrations · Manage

Claude Code running through the Free Claude Code proxy.

Codex CLI using the local FCC Responses provider.

Claude Code native /model picker with FCC gateway models.

Codex native /model picker with the generated FCC catalog.

Star History

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 first so npm is available for those agents.

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

Re-run the same command whenever you want to update. You can review the installers before running them: install.sh and install.ps1.

2. Start The Server

fcc-server

Keep this process running. The startup log shows the Admin UI address:

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

4. Run Your Coding Agent

Claude Code:

fcc-claude

Codex:

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:

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	NVIDIA_NIM_API_KEY	nvidia_nim/nvidia/nemotron-3-super-120b-a12b
OpenRouter	OPENROUTER_API_KEY	open_router/openrouter/free
Google AI Studio (Gemini)	GEMINI_API_KEY	gemini/models/gemini-3.1-flash-lite
DeepSeek	DEEPSEEK_API_KEY	deepseek/deepseek-chat
Mistral La Plateforme	MISTRAL_API_KEY	mistral/devstral-small-latest
Mistral Codestral	CODESTRAL_API_KEY	mistral_codestral/codestral-latest
OpenCode Zen	OPENCODE_API_KEY	opencode/gpt-5.3-codex
OpenCode Go	OPENCODE_API_KEY	opencode_go/minimax-m2.7
Vercel AI Gateway	AI_GATEWAY_API_KEY	vercel/openai/gpt-5.5
Hugging Face Inference Providers	HUGGINGFACE_API_KEY	huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest
Cohere	COHERE_API_KEY	cohere/command-a-plus-05-2026
GitHub Models	GITHUB_MODELS_TOKEN	github_models/openai/gpt-4.1
Wafer	WAFER_API_KEY	wafer/DeepSeek-V4-Pro
Kimi	KIMI_API_KEY	kimi/kimi-k2.5
MiniMax	MINIMAX_API_KEY	minimax/MiniMax-M3
Cerebras Inference	CEREBRAS_API_KEY	cerebras/gpt-oss-120b
Groq	GROQ_API_KEY	groq/llama-3.3-70b-versatile
SambaNova	SAMBANOVA_API_KEY	sambanova/Meta-Llama-3.3-70B-Instruct
Fireworks AI	FIREWORKS_API_KEY	fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct
Cloudflare Workers AI	CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID	cloudflare/@cf/moonshotai/kimi-k2.6
Z.ai	ZAI_API_KEY	zai/glm-5.2
LM Studio	LM_STUDIO_BASE_URL	lmstudio/<model-id>
llama.cpp	LLAMACPP_BASE_URL	llamacpp/<model-id>
Ollama	OLLAMA_BASE_URL	ollama/<model-tag>

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 an Anthropic-compatible /v1/messages endpoint and enough context for the model. Use the local model ID with the llamacpp/ prefix. The default URL is http://localhost:8080/v1.

Ollama

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; do not append /v1.

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. In VS Code settings, edit claudeCode.environmentVariables:

"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. Create or edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

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:

{
  "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:

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

Discord bot

1. Create a bot in the Discord Developer Portal.
2. Enable Message Content Intent and invite it with read, send, and message-history permissions.
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.
2. Get your numeric user ID from @userinfobot.
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: /stop cancels work, /clear resets sessions, and /stats shows session state. Reply to a task message to target only that conversation branch.

Voice notes

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

macOS/Linux:

# 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:

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

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:

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

Windows PowerShell:

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

Project Links

• Report bugs or request features
• Architecture and extension guide
• Contributing guide

License

MIT License. See LICENSE for details.