Skip to content

silentcall/free-claude-code

BranchesTags
 
 

Repository files navigation

🤖 Free Claude Code

Use Claude Code, Codex, Pi, or their IDE extensions through your own provider-backed proxy.

License: MIT Python 3.14 uv Tested with Pytest Type checking: Ty Code style: Ruff Logging: Loguru

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

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.

Star History

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:

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. By default, the Admin UI opens in your browser once the server is healthy. Its address is always shown in the startup log:

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

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, open Model Config, then search the MODEL dropdown and select a model. FCC constructs each slug as <provider-id>/<exact-provider-model-id>; 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 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
Ollama Cloud OLLAMA_API_KEY ollama_cloud/qwen3-coder:480b
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.
  • 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

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.

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

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

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

Admin UI Messaging view with bot and voice settings
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

License

MIT License. See LICENSE for details.

About

Use claude code, codex or pi for free from the terminal, IDE, or you phone like OpenClaw (voice supported)

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 96.5%
  • PowerShell 1.0%
  • Shell 0.8%
  • JavaScript 0.8%
  • CSS 0.5%
  • TypeScript 0.2%
  • Other 0.2%