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

A proxy that routes Claude Code traffic to free, local, or alternative model providers, bypassing Anthropic's paid subscription.

🔥 Key Capabilities & USP

• Multi-Provider Backend Support: Routes Claude Code's API calls to eight different providers including NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama. This eliminates the single-vendor lock-in and recurring subscription cost of Anthropic's paid tier.
• Per-Model Routing: Assigns different providers for Opus, Sonnet, Haiku, and fallback traffic independently. This solves the pain point of optimizing cost vs. capability—use a powerful free provider for complex reasoning and a lightweight local model for simple tasks.
• Local Admin UI: A web interface at /admin for configuring proxy settings, validating changes, and checking provider health. This removes the friction of manual config file editing and provides real-time feedback on provider connectivity.
• Discord/Telegram Bot Wrappers: Optional bot integration enables remote coding sessions with voice-note transcription support. This extends Claude Code's utility to team collaboration and mobile-accessible workflows.
• Streaming & Tool Use: Handles streaming responses, tool use, reasoning blocks, and local request optimizations. This preserves the full Claude Code experience—including real-time output and agentic tool calling—without degradation.

USP: Unlike simple API key swaps, this project provides a production-grade proxy that maintains protocol compatibility with Claude Code's client while offering granular provider routing, an admin dashboard, and optional bot wrappers—all for zero subscription cost.

Technical Architecture

Component	Details
Language	Python 3.14
Package Manager	uv (Astral)
Key Libraries	Pytest (testing), Ty (type checking), Ruff (linting), Loguru (logging)
Proxy Server	Routes Anthropic Messages API calls to provider-specific adapters
Admin UI	Web interface (loopback-only) for configuration management
Provider Adapters	Translate Anthropic API format to provider-specific APIs (NVIDIA, Kimi, OpenRouter, etc.)
Bot Wrappers	Optional Discord/Telegram bots for remote coding with voice transcription
Configuration	Environment variables stored in ~/.config/free-claude-code/.env

Quick Start Guide

Install Python 3.14 and uv (cross-platform):

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

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

Install and start the proxy:

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

Run Claude Code through the proxy:

# Bash
ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 claude

# PowerShell
$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; $env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"; claude

Pros, Cons & Use Cases

Pros

• Zero subscription cost for Claude Code usage with supported free providers
• Flexible provider switching per model tier (Opus, Sonnet, Haiku)
• Admin UI simplifies configuration and debugging
• Local model support (LM Studio, llama.cpp, Ollama) for air-gapped or private workloads
• Bot integration enables team collaboration and voice-driven coding

Cons

• Requires Python 3.14 and uv installation—not a zero-dependency drop-in
• Admin UI is loopback-only, limiting remote management without SSH tunneling
• Some providers require API keys, so "free" may still mean signing up for third-party services
• Model picker support depends on Claude Code opting in to Gateway model discovery—not guaranteed for all versions

Who should NOT use this?

• Enterprise teams with strict compliance requirements who cannot route API traffic through third-party proxies or unapproved providers
• Users who need Anthropic's official SLA, support, and data privacy guarantees—this proxy offers no uptime commitments or data handling assurances
• Developers on Python versions below 3.14 who cannot upgrade their environment
• Teams requiring multi-user admin access—the single-user loopback UI doesn't support team management

Ideal Use Cases

• Individual developers who want to experiment with Claude Code without a paid Anthropic subscription
• Hobbyists and open-source contributors running local models (Ollama, LM Studio) who want Claude Code's interface
• Teams evaluating multiple model providers for cost optimization and performance comparison
• Remote collaboration scenarios using Discord/Telegram bots with voice transcription for pair programming

Community & Activity

With 23,393 stars and recent updates as of May 2026, this project has clearly struck a nerve in the developer community. The star count signals strong validation—developers are actively seeking alternatives to vendor-locked AI tooling. The project's momentum suggests an active maintainer addressing compatibility with the latest Claude Code releases and provider API changes. For a tool that fundamentally alters the economics of using Claude Code, this level of community traction is both impressive and encouraging for long-term maintenance.