Claude Code Free 🚀

Use the official Claude Code CLI entirely for free (or with custom OpenAI-compatible API providers) by redirecting its API requests through a local translating proxy server.

---

How It Works

Claude Code communicates with Anthropic's servers via the ANTHROPIC_BASE_URL API endpoint. This tool starts a local server on http://localhost:3000 which acts as a compatibility layer. By updating Claude Code's configuration:

1. All Claude Code requests are routed to the local proxy server.
2. The proxy server automatically translates Anthropic API calls (both streaming and non-streaming) into standard OpenAI Chat Completions calls.
3. The proxy routes these translated requests to:
   • Your Custom Provider: Defined in custom_key.json (e.g. OpenRouter, Aerolink, or any OpenAI-compatible API endpoint).
   • Free Key Pool: If no custom provider is configured, it auto-rotates through a public repository of free keys (alistaitsacle/free-llm-api-keys), dynamically disabling rate-limited or broken keys so your session remains uninterrupted.
4. The tool presents a model selector menu and boots Claude Code with your chosen model.

---

Features

• Free Tier Keys Rotation: Automatically fetches, tests, rotates, and caches working API keys from public sources.
• Custom OpenAI-Compatible API Support: Seamlessly route Claude Code to OpenRouter, local models (LM Studio, Ollama), or other private APIs.
• Cross-Platform CLI: Written in both Node.js and Python. Run it with a single command on Windows, macOS, and Linux.
• PowerShell Script Fallback: For Windows users who prefer launching via manual shell scripts.
• Automatic Environment Configuration: Sets the appropriate variables and configuration files automatically.

---

Installation

First, ensure you have the official Claude Code CLI installed globally:

npm install -g @anthropic-ai/claude-code

Then install Claude Code Free using either Python (pip) or Node.js (npm):

Option A: Install via npm (Recommended)

In the repository directory, run:

npm install -g .

This registers the global CLI command claude-free.

Option B: Install via pip

In the repository directory, run:

pip install .

This registers the global CLI command claude-free via python entry points.

---

Usage

Simply run:

claude-free

This will:

1. Verify Claude Code is installed.
2. Spin up the Node.js proxy server in the background.
3. Automatically update ~/.claude/settings.json to route through http://localhost:3000/v1 with a dummy key.
4. Display a menu to select your desired AI model.
5. Launch the interactive claude shell.
6. Automatically close the background proxy server when you exit the Claude session.

Running Manually

If you prefer not to use the global CLI, you can launch using PowerShell (Windows only):

1. Start the proxy server:

   node src/proxy.js

2. In a separate terminal, launch the PowerShell script:

   ./scripts/start.ps1

---

Configuration

Custom API Provider / Keys

To use your own API provider instead of the free rotation pool, create a file named custom_key.json in ~/.claude/custom_key.json (or the folder where you run the proxy):

{
  "CUSTOM_API_KEY": "your_api_key_here",
  "CUSTOM_BASE_URL": "https://api.openrouter.ai/v1",
  "Model-name": "claude-3-5-sonnet-latest"
}

Note: The proxy will automatically fall back to the free rotating key pool if custom_key.json is missing or contains "your_api_key_here".

OpenRouter Native Environment Configuration

To configure your system variables to run Claude Code natively with OpenRouter without running the proxy server, run:

./scripts/setup_openrouter.ps1

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.