🤖 Free Claude Code

Use Claude Code, Codex, Pi, editor extensions, or chat bots through your own provider-backed proxy.

Run your coding agents 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, Codex with fcc-codex, or Pi with fcc-pi.
• Switch among 24 cloud and local providers from the Admin UI.
• Use each coding agent's native model picker.
• 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

macOS/Linux:

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

Windows 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 and install.ps1.

2. Start The Server

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:

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

Pi:

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:

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

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 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. Open VS Code's user settings as JSON and add:

"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": "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "value": "1" }
]

Match the port and authentication token to the Admin UI, then reload the extension.

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",
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "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:

"hasCompletedOnboarding": true

If the file does not exist, create it with a complete JSON object:

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

Discord bot

1. Create a bot in the Discord Developer Portal.
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.
2. Get your numeric user ID from @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:

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

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

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:

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

Windows PowerShell:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1")))

Project Links

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

License

MIT License. See LICENSE for details.