Alishahryar1/free-claude-code

⭐ 23,393  ·  Python  ·  GitHub Repo

Use claude-code for free in the terminal, VSCode extension or discord like OpenClaw (voice supported)

1-Sentence Summary

Free proxy routes Claude Code to alternative providers, enabling zero-cost AI coding with local or third-party models.

🔥 Key Capabilities & USP

• Multi-Provider Backend Routing: Routes Claude Code's API traffic to eight different providers including free options (NVIDIA NIM, Kimi) and local models (LM Studio, Ollama, llama.cpp). Solves the core pain point of Anthropic's paid API pricing by giving you complete provider flexibility.

• Per-Model Intelligent Routing: Assign separate providers for Opus, Sonnet, Haiku, and fallback traffic. This means you can use a free provider for simple tasks and a more capable (or local) model for complex reasoning—optimizing both cost and performance.

• Local Admin UI with Validation: A browser-based interface at /admin lets you configure proxy settings, validate changes in real-time, and test provider connectivity. No more guessing if your config is correct—see live feedback.

• Chat Platform Integration: Optional Discord and Telegram bot wrappers enable remote coding sessions through chat platforms, with voice note transcription support via local Whisper or NVIDIA NIM. Turns Claude Code into a collaborative, voice-enabled coding assistant.

USP: This is the only project that gives you a drop-in proxy for Claude Code's full client-side protocol (terminal, VS Code extension, JetBrains) while supporting free, paid, and local models—all without modifying Claude Code itself.

Technical Architecture

Component	Details
Language	Python 3.14
Package Manager	uv (Astral)
Key Dependencies	Loguru (logging), Ruff (code formatting), Pytest (testing), Ty (type checking)
Transport Protocols	OpenAI chat translation + Anthropic Messages API formats
Configuration	Environment variables in ~/.config/free-claude-code/.env
Security	Admin UI restricted to loopback only (403 for remote requests)
Deployment	Single uv tool install command, runs as a local proxy server

Quick Start Guide

# Install requirements (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update
uv python install 3.14

# Install requirements (Windows PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
uv python install 3.14

# Install the proxy
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git

# Start the proxy
free-claude-code

# Run Claude Code with proxy (PowerShell)
$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; $env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"; claude

# Run Claude Code with proxy (Bash)
ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 claude

Pros, Cons & Use Cases

Pros

• Completely free with supported providers like NVIDIA NIM and Kimi
• Works with local models (LM Studio, Ollama, llama.cpp) for offline/private use
• Per-model routing lets you mix free and paid providers intelligently
• Active project with 23,393 stars and growing momentum
• Drop-in replacement—no modifications to Claude Code required

Cons

• Requires Python 3.14 and uv installation, which may conflict with existing Python environments
• Admin UI is local-only—no remote management or web-based monitoring from other devices
• Some providers require API keys (OpenRouter, DeepSeek, Wafer), reducing the "free" aspect for those backends
• Local models require significant hardware (GPU, RAM) and manual setup

Who should NOT use this?

• Enterprise teams needing SLA-backed support—this is a community project with no guarantees
• Users who want a fully managed solution—you must configure and maintain the proxy yourself
• Teams requiring strict security audits—routing through third-party providers introduces data privacy considerations
• Users on Python 3.13 or older—the project mandates Python 3.14

Ideal Use Cases

• Individual developers who want to use Claude Code's interface without paying Anthropic API costs
• Hobbyists and tinkerers experimenting with different model providers (free cloud, local, or hybrid)
• Privacy-conscious users running local models via LM Studio or Ollama while using Claude Code's UI
• Teams on a budget who can accept best-effort performance from free providers like NVIDIA NIM

Community & Activity

With 23,393 stars and a last update on May 10, 2026, this project has clearly struck a nerve in the developer community. The star count alone signals massive interest—this isn't a niche tool, it's a movement. The fact that it's actively maintained (recent updates) means you're not jumping onto a dead project. The combination of free access, local model support, and chat platform integration has clearly resonated with developers tired of API pricing walls. This is the kind of project that could fundamentally change how teams evaluate Claude Code adoption.