diff --git a/README.md b/README.md index e27e4149..0314f968 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # 🤖 Free Claude Code -### Use Claude Code CLI & VSCode for free. No Anthropic API key required. +Use Claude Code CLI, VS Code, JetBrains ACP, or chat bots through your own Anthropic-compatible proxy. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) [![Python 3.14](https://img.shields.io/badge/python-3.14-3776ab.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) @@ -12,77 +12,48 @@ [![Code style: Ruff](https://img.shields.io/badge/code%20formatting-ruff-f5a623.svg?style=for-the-badge)](https://github.com/astral-sh/ruff) [![Logging: Loguru](https://img.shields.io/badge/logging-loguru-4ecdc4.svg?style=for-the-badge)](https://github.com/Delgan/loguru) -A lightweight proxy that routes Claude Code's Anthropic API calls to **NVIDIA NIM** (40 req/min free), **OpenRouter** (hundreds of models), **DeepSeek** (direct Anthropic-compatible API), **LM Studio** (fully local), **llama.cpp** (local with Anthropic endpoints), or **Ollama** (fully local, native Anthropic Messages). +Free Claude Code routes Anthropic Messages API traffic from Claude Code to NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, or Ollama. It keeps Claude Code's client-side protocol stable while letting you choose free, paid, or local models. -[Quick Start](#quick-start) · [Providers](#providers) · [Discord Bot](#discord-bot) · [Configuration](#configuration) · [Development](#development) · [Contributing](#contributing) - ---- +[Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-claude-code) · [Troubleshooting](#troubleshooting) · [Development](#development)
Free Claude Code in action -

Claude Code running via NVIDIA NIM, completely free

-## Features +## What You Get -| Feature | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------- | -| **Zero Cost** | 40 req/min free on NVIDIA NIM. Free models on OpenRouter. Fully local with LM Studio, Ollama, or llama.cpp | -| **Drop-in Replacement** | Set 2 env vars. No modifications to Claude Code CLI or VSCode extension needed | -| **6 Providers** | NVIDIA NIM, OpenRouter, DeepSeek, LM Studio (local), llama.cpp (`llama-server`), Ollama | -| **Per-Model Mapping** | Route Opus / Sonnet / Haiku to different models and providers. Mix providers freely | -| **Thinking Token Support** | Parses `` tags and `reasoning_content` into native Claude thinking blocks | -| **Heuristic Tool Parser** | Models outputting tool calls as text are auto-parsed into structured tool use | -| **Request Optimization** | 5 categories of trivial API calls intercepted locally, saving quota and latency | -| **Smart Rate Limiting** | Proactive rolling-window throttle + reactive 429 exponential backoff + optional concurrency cap | -| **Discord / Telegram Bot** | Remote autonomous coding with tree-based threading, session persistence, and live progress | -| **Subagent Control** | Task tool interception forces `run_in_background=False`. No runaway subagents | -| **Extensible** | Clean `BaseProvider` and `MessagingPlatform` ABCs. Add new providers or platforms easily | +- Drop-in proxy for Claude Code's Anthropic API calls. +- Six provider backends: NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama. +- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers. +- Streaming, tool use, reasoning/thinking block handling, and local request optimizations. +- Optional Discord or Telegram bot wrapper for remote coding sessions. +- Optional voice-note transcription through local Whisper or NVIDIA NIM. ## Quick Start -### Prerequisites +### 1. Install Requirements -1. Get an API key (or use a local provider): - - **NVIDIA NIM**: [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys) - - **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys) - - **DeepSeek**: [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) - - **LM Studio**: No API key needed. Run locally with [LM Studio](https://lmstudio.ai) - - **llama.cpp**: No API key needed. Run `llama-server` locally. - - **Ollama**: No API key needed. Run locally with [Ollama](https://ollama.com) (`ollama serve`). -2. Install [Claude Code](https://github.com/anthropics/claude-code) +Install [Claude Code](https://github.com/anthropics/claude-code), then install `uv` and Python 3.14. -### Install `uv` +macOS/Linux: ```bash -# Recommended installer (works on macOS/Linux without relying on system pip) curl -LsSf https://astral.sh/uv/install.sh | sh - -# Keep uv current if it is already installed uv self update - -# This project requires Python 3.14 uv python install 3.14 ``` -PowerShell (Windows): +Windows PowerShell: ```powershell -# Recommended installer (avoids relying on system pip) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - -# Keep uv current if it is already installed uv self update - -# This project requires Python 3.14 uv python install 3.14 ``` -`pip install uv` can fail on Homebrew-managed Python with `externally-managed-environment` (PEP 668), so prefer the official installer above. - -### Clone & Configure +### 2. Clone And Configure ```bash git clone https://github.com/Alishahryar1/free-claude-code.git @@ -90,178 +61,199 @@ cd free-claude-code cp .env.example .env ``` -Choose your provider and edit `.env`: +PowerShell uses: -
-NVIDIA NIM (40 req/min free, recommended) +```powershell +Copy-Item .env.example .env +``` + +Edit `.env` and choose one provider. For the default NVIDIA NIM path: ```dotenv -NVIDIA_NIM_API_KEY="nvapi-your-key-here" - -MODEL_OPUS= -MODEL_SONNET= -MODEL_HAIKU= -MODEL="nvidia_nim/z-ai/glm4.7" # fallback - -# Per-Claude-model switches for provider reasoning requests and Claude thinking blocks. -# Blank per-model switches inherit ENABLE_MODEL_THINKING. -ENABLE_OPUS_THINKING= -ENABLE_SONNET_THINKING= -ENABLE_HAIKU_THINKING= -ENABLE_MODEL_THINKING=true +NVIDIA_NIM_API_KEY="nvapi-your-key" +MODEL="nvidia_nim/z-ai/glm4.7" +ANTHROPIC_AUTH_TOKEN="freecc" ``` -
+Use any local secret for `ANTHROPIC_AUTH_TOKEN`; Claude Code will send the same value back to this proxy. Leave it empty only for local/private testing. -
-OpenRouter (hundreds of models) - -```dotenv -OPENROUTER_API_KEY="sk-or-your-key-here" - -MODEL_OPUS="open_router/deepseek/deepseek-r1-0528:free" -MODEL_SONNET="open_router/openai/gpt-oss-120b:free" -MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free" -MODEL="open_router/stepfun/step-3.5-flash:free" # fallback -``` - -
- -
-DeepSeek (direct API) - -```dotenv -DEEPSEEK_API_KEY="your-deepseek-key-here" - -MODEL_OPUS="deepseek/deepseek-reasoner" -MODEL_SONNET="deepseek/deepseek-chat" -MODEL_HAIKU="deepseek/deepseek-chat" -MODEL="deepseek/deepseek-chat" # fallback -``` - -
- -
-LM Studio (fully local, no API key) - -```dotenv -MODEL_OPUS="lmstudio/unsloth/MiniMax-M2.5-GGUF" -MODEL_SONNET="lmstudio/unsloth/Qwen3.5-35B-A3B-GGUF" -MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF" -MODEL="lmstudio/unsloth/GLM-4.7-Flash-GGUF" # fallback -``` - -
- -
-llama.cpp (fully local, no API key) - -```dotenv -LLAMACPP_BASE_URL="http://localhost:8080/v1" - -MODEL_OPUS="llamacpp/local-model" -MODEL_SONNET="llamacpp/local-model" -MODEL_HAIKU="llamacpp/local-model" -MODEL="llamacpp/local-model" -``` - -
- -
-Ollama (fully local, no API key) - -```dotenv -OLLAMA_BASE_URL="http://localhost:11434" - -MODEL_OPUS="ollama/llama3.1" -MODEL_SONNET="ollama/llama3.1" -MODEL_HAIKU="ollama/llama3.1" -MODEL="ollama/llama3.1" # fallback -``` - -Install: [ollama.com](https://ollama.com). Pull a model (`ollama pull llama3.1`) and keep the server running (`ollama serve` or the desktop app). Use the same model tag in `MODEL*` that appears in `ollama list` (for example `ollama/llama3.1:8b`). - -
- -
-Mix providers - -Each `MODEL_*` variable can use a different provider. `MODEL` is the fallback for unrecognized Claude models. - -```dotenv -NVIDIA_NIM_API_KEY="nvapi-your-key-here" -OPENROUTER_API_KEY="sk-or-your-key-here" - -MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5" -MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free" -MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF" -MODEL="nvidia_nim/z-ai/glm4.7" # fallback -``` - -
- -> Migration: `NIM_ENABLE_THINKING` and `ENABLE_THINKING` were removed in this release. Use `ENABLE_MODEL_THINKING` as the fallback switch, with optional `ENABLE_OPUS_THINKING`, `ENABLE_SONNET_THINKING`, and `ENABLE_HAIKU_THINKING` overrides. - -
-Optional Authentication (restrict access to your proxy) - -Set `ANTHROPIC_AUTH_TOKEN` in `.env` to require clients to authenticate: - -```dotenv -ANTHROPIC_AUTH_TOKEN="your-secret-token-here" -``` - -**How it works:** -- If `ANTHROPIC_AUTH_TOKEN` is empty (default), no authentication is required (backward compatible) -- If set, clients must provide the same token via the `ANTHROPIC_AUTH_TOKEN` header -- The `claude-pick` script automatically reads the token from `.env` if configured - -**Example usage:** -```bash -# With authentication -ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \ -ANTHROPIC_BASE_URL="http://localhost:8082" claude - -# claude-pick automatically uses the configured token -claude-pick -``` - -Use this feature if: -- Running the proxy on a public network -- Sharing the server with others but restricting access -- Wanting an additional layer of security - -
- -### Run It - -**Terminal 1:** Start the proxy server: +### 3. Start The Proxy ```bash uv run uvicorn server:app --host 0.0.0.0 --port 8082 ``` -**Terminal 2:** Run Claude Code: +Package install alternative: -Point `ANTHROPIC_BASE_URL` at the proxy root URL, not `http://localhost:8082/v1`. +```bash +uv tool install git+https://github.com/Alishahryar1/free-claude-code.git +fcc-init +free-claude-code +``` + +`fcc-init` creates `~/.config/free-claude-code/.env` from the bundled template. + +### 4. Run Claude Code + +Point `ANTHROPIC_BASE_URL` at the proxy root. Do not append `/v1`. + +PowerShell: -#### Powershell ```powershell $env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude ``` -#### Bash + +Bash: + ```bash ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude ``` -That's it! Claude Code now uses your configured provider for free. +## Choose A Provider + +Model values use this format: + +```text +provider_id/model/name +``` + +`MODEL` is the fallback. `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` override routing for requests that Claude Code sends for those tiers. + +| Provider | Prefix | Transport | Key | Default base URL | +| --- | --- | --- | --- | --- | +| NVIDIA NIM | `nvidia_nim/...` | OpenAI chat translation | `NVIDIA_NIM_API_KEY` | `https://integrate.api.nvidia.com/v1` | +| OpenRouter | `open_router/...` | Anthropic Messages | `OPENROUTER_API_KEY` | `https://openrouter.ai/api/v1` | +| DeepSeek | `deepseek/...` | Anthropic Messages | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/anthropic` | +| LM Studio | `lmstudio/...` | Anthropic Messages | none | `http://localhost:1234/v1` | +| llama.cpp | `llamacpp/...` | Anthropic Messages | none | `http://localhost:8080/v1` | +| Ollama | `ollama/...` | Anthropic Messages | none | `http://localhost:11434` |
-VSCode Extension Setup +NVIDIA NIM -1. Start the proxy server (same as above). -2. Open Settings (`Ctrl + ,`) and search for `claude-code.environmentVariables`. -3. Click **Edit in settings.json** and add: +Get a key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys). + +```dotenv +NVIDIA_NIM_API_KEY="nvapi-your-key" +MODEL="nvidia_nim/z-ai/glm4.7" +``` + +Popular examples: + +- `nvidia_nim/z-ai/glm4.7` +- `nvidia_nim/z-ai/glm5` +- `nvidia_nim/moonshotai/kimi-k2.5` +- `nvidia_nim/minimaxai/minimax-m2.5` + +Browse models at [build.nvidia.com](https://build.nvidia.com/explore/discover). A cached model list is also kept in [`nvidia_nim_models.json`](nvidia_nim_models.json). + +
+ +
+OpenRouter + +Get a key at [openrouter.ai/keys](https://openrouter.ai/keys). + +```dotenv +OPENROUTER_API_KEY="sk-or-your-key" +MODEL="open_router/stepfun/step-3.5-flash:free" +``` + +Browse [all models](https://openrouter.ai/models) or [free models](https://openrouter.ai/collections/free-models). + +
+ +
+DeepSeek + +Get a key at [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys). + +```dotenv +DEEPSEEK_API_KEY="your-deepseek-key" +MODEL="deepseek/deepseek-chat" +``` + +This provider uses DeepSeek's Anthropic-compatible endpoint, not the OpenAI chat-completions endpoint. + +
+ +
+LM Studio + +Start LM Studio's local server, load a model, then configure: + +```dotenv +LM_STUDIO_BASE_URL="http://localhost:1234/v1" +MODEL="lmstudio/your-loaded-model" +``` + +Use the model identifier shown by LM Studio. Prefer models with tool-use support for Claude Code workflows. + +
+ +
+llama.cpp + +Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests. + +```dotenv +LLAMACPP_BASE_URL="http://localhost:8080/v1" +MODEL="llamacpp/local-model" +``` + +For local coding models, context size matters. If llama.cpp returns HTTP 400 for normal Claude Code requests, increase `--ctx-size` and verify the model/server build supports the requested features. + +
+ +
+Ollama + +Run Ollama and pull a model: + +```bash +ollama pull llama3.1 +ollama serve +``` + +Then configure the proxy. `OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. + +```dotenv +OLLAMA_BASE_URL="http://localhost:11434" +MODEL="ollama/llama3.1" +``` + +Use the same tag shown by `ollama list`, for example `ollama/llama3.1:8b`. + +
+ +
+Mix providers by model tier + +Each tier can use a different provider: + +```dotenv +NVIDIA_NIM_API_KEY="nvapi-your-key" +OPENROUTER_API_KEY="sk-or-your-key" + +MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5" +MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free" +MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF" +MODEL="nvidia_nim/z-ai/glm4.7" +``` + +
+ +## Connect Claude Code + +### Claude Code CLI + +```bash +ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude +``` + +### VS Code Extension + +Open Settings, search for `claude-code.environmentVariables`, choose **Edit in settings.json**, and add: ```json "claudeCode.environmentVariables": [ @@ -270,433 +262,277 @@ That's it! Claude Code now uses your configured provider for free. ] ``` -4. Reload extensions. -5. **If you see the login screen**: Click **Anthropic Console**, then authorize. The extension will start working. You may be redirected to buy credits in the browser; ignore it — the extension already works. +Reload the extension. If the extension shows a login screen, choose the Anthropic Console path once; the local proxy still handles model traffic after the environment variables are active. -To switch back to Anthropic models, comment out the added block and reload extensions. +### JetBrains ACP - +Edit the installed Claude ACP config: +- Windows: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json` +- Linux/macOS: `~/.jetbrains/acp.json` -
-IntelliJ Extension Setup +Set the environment for `acp.registry.claude-acp`: -1. Open the configuration file: - - **Windows**: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json` - - **Linux/macOS**: `~/.jetbrains/acp.json` -2. Inside acp.registry.claude-acp, change: - - ``` - "env": {} - ``` - to - - ``` - "env": { - "ANTHROPIC_AUTH_TOKEN": "freecc", - "ANTHROPIC_BASE_URL": "http://localhost:8082" - } - ``` -3. Start the proxy server -4. Restart IDE - -
- -
-Multi-Model Support (Model Picker) - -`claude-pick` is an interactive model selector that lets you choose any model from your active provider each time you launch Claude, without editing `MODEL` in `.env`. - -https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645 - -**1. Install [fzf](https://github.com/junegunn/fzf)**: - -```bash -brew install fzf # macOS/Linux +```json +"env": { + "ANTHROPIC_BASE_URL": "http://localhost:8082", + "ANTHROPIC_AUTH_TOKEN": "freecc" +} ``` -**2. Add the alias to `~/.zshrc` or `~/.bashrc`:** +Restart the IDE after changing the file. + +### Model Picker + +`claude-pick` lets you choose a model at launch time. ```bash +brew install fzf alias claude-pick="/absolute/path/to/free-claude-code/claude-pick" +claude-pick ``` -Then reload your shell (`source ~/.zshrc` or `source ~/.bashrc`) and run `claude-pick`. - -**Or use a fixed model alias** (no picker needed): +You can also create fixed aliases: ```bash alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude' ``` -
+## Optional Integrations -### Install as a Package (no clone needed) +### Discord And Telegram Bots -```bash -uv tool install git+https://github.com/Alishahryar1/free-claude-code.git -fcc-init # creates ~/.config/free-claude-code/.env from the built-in template -``` +The bot wrapper runs Claude Code sessions remotely, streams progress, supports reply-based conversation branches, and can stop or clear tasks. -Edit `~/.config/free-claude-code/.env` with your API keys and model names, then: - -```bash -free-claude-code # starts the server -``` - -> To update: `uv tool upgrade free-claude-code` - ---- - -## How It Works - -``` -┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ -│ Claude Code │───────>│ Free Claude Code │───────>│ LLM Provider │ -│ CLI / VSCode │<───────│ Proxy (:8082) │<───────│ NIM / OR / LMS │ -└─────────────────┘ └──────────────────────┘ └──────────────────┘ - Anthropic API Native Anthropic - format (SSE) or OpenAI chat SSE -``` - -- **Transparent proxy**: Claude Code sends standard Anthropic API requests; the proxy forwards them to your configured provider -- **Per-model routing**: Opus / Sonnet / Haiku requests resolve to their model-specific backend, with `MODEL` as fallback -- **Request optimization**: 5 categories of trivial requests (quota probes, title generation, prefix detection, suggestions, filepath extraction) are intercepted and responded to locally without using API quota -- **Format handling**: OpenRouter, LM Studio, llama.cpp, and Ollama use native Anthropic Messages endpoints; NIM and DeepSeek use shared OpenAI chat translation -- **Thinking tokens**: `` tags and `reasoning_content` fields are converted into native Claude thinking blocks when the resolved model's thinking switch is enabled - -The proxy also exposes Claude-compatible probe routes: `GET /v1/models`, `POST /v1/messages`, `POST /v1/messages/count_tokens`, plus `HEAD`/`OPTIONS` support for the common probe endpoints. - ---- - -## Providers - -| Provider | Cost | Rate Limit | Best For | -| -------------- | ------------ | ---------- | ------------------------------------ | -| **NVIDIA NIM** | Free | 40 req/min | Daily driver, generous free tier | -| **OpenRouter** | Free / Paid | Varies | Model variety, fallback options | -| **DeepSeek** | Usage-based | Varies | Native Anthropic Messages on DeepSeek's API | -| **LM Studio** | Free (local) | Unlimited | Privacy, offline use, no rate limits | -| **llama.cpp** | Free (local) | Unlimited | Lightweight local inference engine | -| **Ollama** | Free (local) | Unlimited | Easy local LLM runtime, native Anthropic API | - -Models use a prefix format: `provider_prefix/model/name`. An invalid prefix causes an error. - -| Provider | `MODEL` prefix | API Key Variable | Default Base URL | -| ---------- | ----------------- | -------------------- | ----------------------------- | -| NVIDIA NIM | `nvidia_nim/...` | `NVIDIA_NIM_API_KEY` | `integrate.api.nvidia.com/v1` | -| OpenRouter | `open_router/...` | `OPENROUTER_API_KEY` | `openrouter.ai/api/v1` | -| DeepSeek | `deepseek/...` | `DEEPSEEK_API_KEY` | `api.deepseek.com/anthropic` | -| LM Studio | `lmstudio/...` | (none) | `localhost:1234/v1` | -| llama.cpp | `llamacpp/...` | (none) | `localhost:8080/v1` | -| Ollama | `ollama/...` | (none) | `localhost:11434` | - -
-NVIDIA NIM models - -Popular models (full list in [`nvidia_nim_models.json`](nvidia_nim_models.json)): - -- `nvidia_nim/minimaxai/minimax-m2.5` -- `nvidia_nim/qwen/qwen3.5-397b-a17b` -- `nvidia_nim/z-ai/glm5` -- `nvidia_nim/moonshotai/kimi-k2.5` -- `nvidia_nim/stepfun-ai/step-3.5-flash` - -Browse: [build.nvidia.com](https://build.nvidia.com/explore/discover) · Update list: `curl "https://integrate.api.nvidia.com/v1/models" > nvidia_nim_models.json` - -
- -
-OpenRouter models - -Popular free models: - -- `open_router/arcee-ai/trinity-large-preview:free` -- `open_router/stepfun/step-3.5-flash:free` -- `open_router/deepseek/deepseek-r1-0528:free` -- `open_router/openai/gpt-oss-120b:free` - -Browse: [openrouter.ai/models](https://openrouter.ai/models) · [Free models](https://openrouter.ai/collections/free-models) - -
- -
-DeepSeek models - -The `deepseek` provider uses DeepSeek's **Anthropic-compatible** `POST /v1/messages` entrypoint -(HTTP base `https://api.deepseek.com/anthropic`), not the OpenAI `chat/completions` API. Some -Anthropic request features are unsupported; see the DeepSeek API docs for limits. - -- `deepseek/deepseek-v4-pro` / `deepseek/deepseek-v4-flash` (recommended for smokes and tools+thinking) -- `deepseek/deepseek-chat` / `deepseek/deepseek-reasoner` (older model ids may still be available) - -Browse: [api-docs.deepseek.com](https://api-docs.deepseek.com) - -
- -
-LM Studio models - -Run models locally with [LM Studio](https://lmstudio.ai). Load a model in the Chat or Developer tab, then set `MODEL` to its identifier. - -Examples with native tool-use support: - -- `LiquidAI/LFM2-24B-A2B-GGUF` -- `unsloth/MiniMax-M2.5-GGUF` -- `unsloth/GLM-4.7-Flash-GGUF` -- `unsloth/Qwen3.5-35B-A3B-GGUF` - -Browse: [model.lmstudio.ai](https://model.lmstudio.ai) - -
- -
-llama.cpp models - -Run models locally using `llama-server`. Ensure you have a tool-capable GGUF. Set `MODEL` to whatever arbitrary name you'd like (e.g. `llamacpp/my-model`), as `llama-server` ignores the model name when run via `/v1/messages`. - -See the Unsloth docs for detailed instructions and capable models: -[https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b](https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b) - -
- -
-Ollama models - -Run models locally with [Ollama](https://ollama.com). Pull a model, then set `MODEL` to `ollama/` where `` matches the name in `ollama list` (for example `ollama/llama3.1:8b` or `ollama/qwen2.5-coder:7b`). - -- `OLLAMA_BASE_URL` is the **Ollama server root** (default `http://localhost:11434`). Do not append `/v1`; the proxy uses Ollama's native Anthropic Messages support at that host. -- Override `OLLAMA_BASE_URL` only if Ollama listens on another address or port. - -```bash -ollama pull llama3.1 -ollama serve # or use the desktop app, which keeps the server running -``` - -Browse: [ollama.com/library](https://ollama.com/library) - -
- ---- - -## Discord Bot - -Control Claude Code remotely from Discord (or Telegram). Send tasks, watch live progress, and manage multiple concurrent sessions. - -**Capabilities:** - -- Tree-based message threading: reply to a message to fork the conversation -- Session persistence across server restarts -- Live streaming of thinking tokens, tool calls, and results -- Unlimited concurrent Claude CLI sessions (concurrency controlled by `PROVIDER_MAX_CONCURRENCY`) -- Voice notes: send voice messages; they are transcribed and processed as regular prompts -- Commands: `/stop` (cancel a task; reply to a message to stop only that task), `/clear` (reset all sessions, or reply to clear a branch), `/stats` - -### Setup - -1. **Create a Discord Bot**: Go to [Discord Developer Portal](https://discord.com/developers/applications), create an application, add a bot, and copy the token. Enable **Message Content Intent** under Bot settings. - -2. **Edit `.env`:** +Discord minimum config: ```dotenv MESSAGING_PLATFORM="discord" -DISCORD_BOT_TOKEN="your_discord_bot_token" -ALLOWED_DISCORD_CHANNELS="123456789,987654321" -``` - -> Enable Developer Mode in Discord (Settings → Advanced), then right-click a channel and "Copy ID". Comma-separate multiple channels. If empty, no channels are allowed. - -3. **Configure the workspace** (where Claude will operate): - -```dotenv +DISCORD_BOT_TOKEN="your-discord-bot-token" +ALLOWED_DISCORD_CHANNELS="123456789" CLAUDE_WORKSPACE="./agent_workspace" ALLOWED_DIR="C:/Users/yourname/projects" ``` -4. **Start the server:** +Create the bot in the [Discord Developer Portal](https://discord.com/developers/applications), enable Message Content Intent, and invite it with read/send/history permissions. -```bash -uv run uvicorn server:app --host 0.0.0.0 --port 8082 -``` - -5. **Invite the bot** via OAuth2 URL Generator (scopes: `bot`, permissions: Read Messages, Send Messages, Manage Messages, Read Message History). - -### Telegram - -Set `MESSAGING_PLATFORM=telegram` and configure: +Telegram minimum config: ```dotenv -TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ" -ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id" +MESSAGING_PLATFORM="telegram" +TELEGRAM_BOT_TOKEN="123456789:ABC..." +ALLOWED_TELEGRAM_USER_ID="your-user-id" +CLAUDE_WORKSPACE="./agent_workspace" +ALLOWED_DIR="C:/Users/yourname/projects" ``` -Get a token from [@BotFather](https://t.me/BotFather); find your user ID via [@userinfobot](https://t.me/userinfobot). +Get a token from [@BotFather](https://t.me/BotFather) and your user ID from [@userinfobot](https://t.me/userinfobot). + +Useful commands: + +- `/stop` cancels a task; reply to a task message to stop only that branch. +- `/clear` resets sessions; reply to clear one branch. +- `/stats` shows session state. ### Voice Notes -Send voice messages on Discord or Telegram; they are transcribed and processed as regular prompts. - -| Backend | Description | API Key | -| --------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- | -| **Local Whisper** (default) | [Hugging Face Whisper](https://huggingface.co/openai/whisper-large-v3-turbo) — free, offline, CUDA compatible | not required | -| **NVIDIA NIM** | Whisper/Parakeet models via gRPC | `NVIDIA_NIM_API_KEY` | - -**Install the voice extras:** +Voice notes work on Discord and Telegram. Choose one backend: ```bash -# If you cloned the repo: -uv sync --extra voice_local # Local Whisper -uv sync --extra voice # NVIDIA NIM -uv sync --extra voice --extra voice_local # Both - -# If you installed as a package (no clone): -uv tool install "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git" -uv tool install "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git" -uv tool install "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git" +uv sync --extra voice_local +uv sync --extra voice +uv sync --extra voice --extra voice_local ``` -Configure via `WHISPER_DEVICE` (`cpu` | `cuda` | `nvidia_nim`) and `WHISPER_MODEL`. See the [Configuration](#configuration) table for all voice variables and supported model values. +```dotenv +VOICE_NOTE_ENABLED=true +WHISPER_DEVICE="cpu" # cpu | cuda | nvidia_nim +WHISPER_MODEL="base" +HF_TOKEN="" +``` ---- +Use `WHISPER_DEVICE="nvidia_nim"` with the `voice` extra and `NVIDIA_NIM_API_KEY` for NVIDIA-hosted transcription. -## Configuration +## Configuration Reference -### Core +[`.env.example`](.env.example) is the canonical list of variables. The sections below are the ones most users change. -| Variable | Description | Default | -| -------------------- | --------------------------------------------------------------------- | ------------------------------------------------- | -| `MODEL` | Fallback model (`provider/model/name` format; invalid prefix → error) | `nvidia_nim/z-ai/glm4.7` | -| `MODEL_OPUS` | Model for Claude Opus requests; empty falls back to `MODEL` | empty | -| `MODEL_SONNET` | Model for Claude Sonnet requests; empty falls back to `MODEL` | empty | -| `MODEL_HAIKU` | Model for Claude Haiku requests; empty falls back to `MODEL` | empty | -| `NVIDIA_NIM_API_KEY` | NVIDIA API key | required for NIM | -| `ENABLE_MODEL_THINKING` | Fallback switch for provider reasoning requests and Claude thinking blocks. Set `false` to hide thinking unless a model tier overrides it. | `true` | -| `ENABLE_OPUS_THINKING` | Optional thinking switch for Claude Opus requests; empty inherits `ENABLE_MODEL_THINKING`. | empty | -| `ENABLE_SONNET_THINKING` | Optional thinking switch for Claude Sonnet requests; empty inherits `ENABLE_MODEL_THINKING`. | empty | -| `ENABLE_HAIKU_THINKING` | Optional thinking switch for Claude Haiku requests; empty inherits `ENABLE_MODEL_THINKING`. | empty | -| `OPENROUTER_API_KEY` | OpenRouter API key | required for OpenRouter | -| `DEEPSEEK_API_KEY` | DeepSeek API key | required for DeepSeek | -| `LM_STUDIO_BASE_URL` | LM Studio server URL | `http://localhost:1234/v1` | -| `LLAMACPP_BASE_URL` | llama.cpp server URL | `http://localhost:8080/v1` | -| `NVIDIA_NIM_PROXY` | Optional proxy URL for NVIDIA NIM requests (`http://...` or `socks5://...`) | `""` | -| `OPENROUTER_PROXY` | Optional proxy URL for OpenRouter requests (`http://...` or `socks5://...`) | `""` | -| `LMSTUDIO_PROXY` | Optional proxy URL for LM Studio requests (`http://...` or `socks5://...`) | `""` | -| `LLAMACPP_PROXY` | Optional proxy URL for llama.cpp requests (`http://...` or `socks5://...`) | `""` | -| `OLLAMA_BASE_URL` | Ollama server root URL | `http://localhost:11434` | +### Model Routing -### Rate Limiting & Timeouts +```dotenv +MODEL="nvidia_nim/z-ai/glm4.7" +MODEL_OPUS= +MODEL_SONNET= +MODEL_HAIKU= +ENABLE_MODEL_THINKING=true +ENABLE_OPUS_THINKING= +ENABLE_SONNET_THINKING= +ENABLE_HAIKU_THINKING= +``` -| Variable | Description | Default | -| -------------------------- | ----------------------------------------- | ------- | -| `PROVIDER_RATE_LIMIT` | LLM API requests per window | `40` | -| `PROVIDER_RATE_WINDOW` | Rate limit window (seconds) | `60` | -| `PROVIDER_MAX_CONCURRENCY` | Max simultaneous open provider streams | `5` | -| `HTTP_READ_TIMEOUT` | Read timeout for provider requests (s) | `120` | -| `HTTP_WRITE_TIMEOUT` | Write timeout for provider requests (s) | `10` | -| `HTTP_CONNECT_TIMEOUT` | Connect timeout for provider requests (s) | `10` | +Blank per-tier values inherit the fallback. Blank thinking overrides inherit `ENABLE_MODEL_THINKING`. -### Messaging & Voice +### Provider Keys And URLs -| Variable | Description | Default | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | -| `MESSAGING_PLATFORM` | `discord` or `telegram` | `discord` | -| `DISCORD_BOT_TOKEN` | Discord bot token | `""` | -| `ALLOWED_DISCORD_CHANNELS` | Comma-separated channel IDs (empty = none allowed) | `""` | -| `TELEGRAM_BOT_TOKEN` | Telegram bot token | `""` | -| `ALLOWED_TELEGRAM_USER_ID` | Allowed Telegram user ID | `""` | -| `CLAUDE_WORKSPACE` | Directory where the agent operates | `./agent_workspace` | -| `ALLOWED_DIR` | Allowed directories for the agent | `""` | -| `MESSAGING_RATE_LIMIT` | Messaging messages per window | `1` | -| `MESSAGING_RATE_WINDOW` | Messaging window (seconds) | `1` | -| `VOICE_NOTE_ENABLED` | Enable voice note handling | `true` | -| `WHISPER_DEVICE` | `cpu` \| `cuda` \| `nvidia_nim` | `cpu` | -| `WHISPER_MODEL` | Whisper model (local: `tiny`/`base`/`small`/`medium`/`large-v2`/`large-v3`/`large-v3-turbo`; NIM: `openai/whisper-large-v3`, `nvidia/parakeet-ctc-1.1b-asr`, etc.) | `base` | -| `HF_TOKEN` | Hugging Face token for faster downloads (local Whisper, optional) | — | +```dotenv +NVIDIA_NIM_API_KEY="" +OPENROUTER_API_KEY="" +DEEPSEEK_API_KEY="" +LM_STUDIO_BASE_URL="http://localhost:1234/v1" +LLAMACPP_BASE_URL="http://localhost:8080/v1" +OLLAMA_BASE_URL="http://localhost:11434" +``` -
-Advanced: Request optimization flags +Proxy settings are per provider: -These are enabled by default and intercept trivial Claude Code requests locally to save API quota. +```dotenv +NVIDIA_NIM_PROXY="" +OPENROUTER_PROXY="" +LMSTUDIO_PROXY="" +LLAMACPP_PROXY="" +``` -| Variable | Description | Default | -| --------------------------------- | ------------------------------ | ------- | -| `FAST_PREFIX_DETECTION` | Enable fast prefix detection | `true` | -| `ENABLE_NETWORK_PROBE_MOCK` | Mock network probe requests | `true` | -| `ENABLE_TITLE_GENERATION_SKIP` | Skip title generation requests | `true` | -| `ENABLE_SUGGESTION_MODE_SKIP` | Skip suggestion mode requests | `true` | -| `ENABLE_FILEPATH_EXTRACTION_MOCK` | Mock filepath extraction | `true` | +### Rate Limits And Timeouts -
+```dotenv +PROVIDER_RATE_LIMIT=1 +PROVIDER_RATE_WINDOW=3 +PROVIDER_MAX_CONCURRENCY=5 +HTTP_READ_TIMEOUT=120 +HTTP_WRITE_TIMEOUT=10 +HTTP_CONNECT_TIMEOUT=10 +``` -See [`.env.example`](.env.example) for all supported parameters. +Use lower limits for free hosted providers; local providers can usually tolerate higher concurrency if the machine can handle it. ---- +### Security And Diagnostics + +```dotenv +ANTHROPIC_AUTH_TOKEN= +LOG_RAW_API_PAYLOADS=false +LOG_RAW_SSE_EVENTS=false +LOG_API_ERROR_TRACEBACKS=false +LOG_RAW_MESSAGING_CONTENT=false +LOG_RAW_CLI_DIAGNOSTICS=false +LOG_MESSAGING_ERROR_DETAILS=false +``` + +Raw logging flags can expose prompts, tool arguments, paths, and model output. Keep them off unless you are debugging locally. + +### Local Web Tools + +```dotenv +ENABLE_WEB_SERVER_TOOLS=true +WEB_FETCH_ALLOWED_SCHEMES=http,https +WEB_FETCH_ALLOW_PRIVATE_NETWORKS=false +``` + +These tools perform outbound HTTP from the proxy. Keep private-network access disabled unless you are in a controlled lab environment. + +## Troubleshooting + +### Claude Code says `undefined ... input_tokens`, `$.speed`, or malformed response + +Update to the latest commit first. Older versions could emit invalid usage metadata in streaming responses. Then check: + +- `ANTHROPIC_BASE_URL` is `http://localhost:8082`, not `http://localhost:8082/v1`. +- The proxy is returning Server-Sent Events for `/v1/messages`. +- `server.log` contains no upstream 400/500 response before the malformed-response error. + +### llama.cpp or LM Studio returns HTTP 400 + +This usually means the local runtime rejected the Anthropic Messages request before the proxy could stream a model answer. + +Check: + +- The local server supports `POST /v1/messages`. +- The model and runtime support the requested context length and tools. +- llama.cpp was started with enough `--ctx-size` for Claude Code prompts. +- The configured base URL includes `/v1` for LM Studio and llama.cpp. + +### Provider disconnects during streaming + +Errors like `incomplete chunked read`, `server disconnected`, or a peer closing the body usually come from the upstream provider or gateway. Reduce concurrency, raise timeouts, or retry later. + +### Tool calls work on one model but not another + +Tool support is model and provider dependent. Some OpenAI-compatible models emit malformed tool-call deltas, omit tool names, or return tool calls as plain text. Try another model or provider before assuming the proxy is broken. + +### The VS Code extension still shows a login screen + +Confirm the extension environment variables are set, then reload the extension or restart VS Code. The browser login flow may still appear once; the local proxy is used when `ANTHROPIC_BASE_URL` is active in the extension process. + +## How It Works + +```text +Claude Code CLI / IDE + | + | Anthropic Messages API + v +Free Claude Code proxy (:8082) + | + | provider-specific request/stream adapter + v +NIM / OpenRouter / DeepSeek / LM Studio / llama.cpp / Ollama +``` + +Important pieces: + +- FastAPI exposes Anthropic-compatible routes such as `/v1/messages`, `/v1/messages/count_tokens`, and `/v1/models`. +- Model routing resolves the Claude model name to `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, or `MODEL`. +- NIM uses OpenAI chat streaming translated into Anthropic SSE. +- OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports. +- The proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape Claude Code expects. +- Request optimizations answer trivial Claude Code probes locally to save latency and quota. ## Development ### Project Structure -``` +```text free-claude-code/ -├── server.py # Entry point -├── api/ # FastAPI routes, API service layer, model routing, request detection, optimizations -├── core/ # Shared Anthropic protocol helpers, SSE, conversion, parsers, token counting -├── providers/ # Provider registry, scoped runtime state, OpenAI chat + Anthropic messages transports -├── messaging/ # MessagingPlatform ABC + Discord/Telegram bots, commands, voice, session management -├── config/ # Settings, NIM config, logging -├── cli/ # CLI session and process management -└── tests/ # Pytest test suite +├── server.py # ASGI entry point +├── api/ # FastAPI routes, service layer, routing, optimizations +├── core/ # Shared Anthropic protocol helpers and SSE utilities +├── providers/ # Provider transports, registry, rate limiting +├── messaging/ # Discord/Telegram adapters, sessions, voice +├── cli/ # Package entry points and Claude process management +├── config/ # Settings, provider catalog, logging +└── tests/ # Unit and contract tests ``` ### Commands ```bash -uv run ruff format # Format code -uv run ruff check # Lint -uv run ty check # Type checking -uv run pytest # Run tests +uv run ruff format +uv run ruff check +uv run ty check +uv run pytest ``` +Run them in that order before pushing. CI enforces the same checks. + +### Package Scripts + +`pyproject.toml` installs: + +- `free-claude-code`: starts the proxy with configured host and port. +- `fcc-init`: creates the user config template at `~/.config/free-claude-code/.env`. + ### Extending -**Adding an OpenAI-compatible provider** (Groq, Together AI, etc.) — extend `OpenAIChatTransport`, then add a descriptor in the provider registry: - -```python -from providers.openai_compat import OpenAIChatTransport -from providers.base import ProviderConfig - -class MyProvider(OpenAIChatTransport): - def __init__(self, config: ProviderConfig): - super().__init__(config, provider_name="MYPROVIDER", - base_url="https://api.example.com/v1", api_key=config.api_key) -``` - -**Adding a native Anthropic provider** — extend `AnthropicMessagesTransport`, then add a descriptor in `providers.registry`. - -**Adding a fully custom provider** — extend `BaseProvider` directly, implement `stream_response()`, and register its descriptor. - -**Adding a messaging platform** — extend `MessagingPlatform` in `messaging/` and implement `start()`, `stop()`, `send_message()`, `edit_message()`, and `on_message()`. - ---- +- Add OpenAI-compatible providers by extending `OpenAIChatTransport`. +- Add Anthropic Messages providers by extending `AnthropicMessagesTransport`. +- Register provider metadata in `config.provider_catalog` and factory wiring in `providers.registry`. +- Add messaging platforms by implementing the `MessagingPlatform` interface in `messaging/`. ## Contributing -- Report bugs or suggest features via [Issues](https://github.com/Alishahryar1/free-claude-code/issues) -- Add new LLM providers (Groq, Together AI, etc.) -- Add new messaging platforms (Slack, etc.) -- Improve test coverage -- Not accepting Docker integration PRs for now - -```bash -git checkout -b my-feature -uv run ruff format && uv run ruff check && uv run ty check && uv run pytest -# Open a pull request -``` - ---- +- Report bugs and feature requests in [Issues](https://github.com/Alishahryar1/free-claude-code/issues). +- Keep changes small and covered by focused tests. +- Do not add Docker integration unless maintainers ask for it. +- Run the full check sequence before opening a pull request. ## License MIT License. See [LICENSE](LICENSE) for details. - -Built with [FastAPI](https://fastapi.tiangolo.com/), [OpenAI Python SDK](https://github.com/openai/openai-python), [discord.py](https://github.com/Rapptz/discord.py), and [python-telegram-bot](https://python-telegram-bot.org/).