Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Updated README
Alishahryar1053beff19e06
diff --git a/README.md b/README.mdindex 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.[](https://opensource.org/licenses/MIT)[](https://www.python.org/downloads/)@@ -12,77 +12,48 @@[](https://github.com/astral-sh/ruff)[](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)</div><div align="center"><img src="pic.png" alt="Free Claude Code in action" width="700">- <p><em>Claude Code running via NVIDIA NIM, completely free</em></p></div>-## Features--| 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 `<think>` 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 |+## What You Get++- 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 installeduv self update--# This project requires Python 3.14uv 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 installeduv self update--# This project requires Python 3.14uv 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```bashgit clone https://github.com/Alishahryar1/free-claude-code.git@@ -90,178 +61,199 @@ cd free-claude-codecp .env.example .env```-Choose your provider and edit `.env`:+PowerShell uses:-<details>-<summary><b>NVIDIA NIM</b> (40 req/min free, recommended)</summary>+```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"+NVIDIA_NIM_API_KEY="nvapi-your-key"+MODEL="nvidia_nim/z-ai/glm4.7"+ANTHROPIC_AUTH_TOKEN="freecc"+```-MODEL_OPUS=-MODEL_SONNET=-MODEL_HAIKU=-MODEL="nvidia_nim/z-ai/glm4.7" # fallback+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.-# 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+### 3. Start The Proxy++```bash+uv run uvicorn server:app --host 0.0.0.0 --port 8082```-</details>+Package install alternative:-<details>-<summary><b>OpenRouter</b> (hundreds of models)</summary>+```bash+uv tool install git+https://github.com/Alishahryar1/free-claude-code.git+fcc-init+free-claude-code+```-```dotenv-OPENROUTER_API_KEY="sk-or-your-key-here"+`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:-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+```powershell+$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude```-</details>+Bash:-<details>-<summary><b>DeepSeek</b> (direct API)</summary>+```bash+ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude+```-```dotenv-DEEPSEEK_API_KEY="your-deepseek-key-here"+## Choose A Provider++Model values use this format:-MODEL_OPUS="deepseek/deepseek-reasoner"-MODEL_SONNET="deepseek/deepseek-chat"-MODEL_HAIKU="deepseek/deepseek-chat"-MODEL="deepseek/deepseek-chat" # fallback+```text+provider_id/model/name```-</details>+`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` |<details>-<summary><b>LM Studio</b> (fully local, no API key)</summary>+<summary><b>NVIDIA NIM</b></summary>++Get a key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).```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+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).+</details><details>-<summary><b>llama.cpp</b> (fully local, no API key)</summary>+<summary><b>OpenRouter</b></summary>-```dotenv-LLAMACPP_BASE_URL="http://localhost:8080/v1"+Get a key at [openrouter.ai/keys](https://openrouter.ai/keys).-MODEL_OPUS="llamacpp/local-model"-MODEL_SONNET="llamacpp/local-model"-MODEL_HAIKU="llamacpp/local-model"-MODEL="llamacpp/local-model"+```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).+</details><details>-<summary><b>Ollama</b> (fully local, no API key)</summary>+<summary><b>DeepSeek</b></summary>-```dotenv-OLLAMA_BASE_URL="http://localhost:11434"+Get a key at [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys).-MODEL_OPUS="ollama/llama3.1"-MODEL_SONNET="ollama/llama3.1"-MODEL_HAIKU="ollama/llama3.1"-MODEL="ollama/llama3.1" # fallback+```dotenv+DEEPSEEK_API_KEY="your-deepseek-key"+MODEL="deepseek/deepseek-chat"```-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`).+This provider uses DeepSeek's Anthropic-compatible endpoint, not the OpenAI chat-completions endpoint.</details><details>-<summary><b>Mix providers</b></summary>+<summary><b>LM Studio</b></summary>-Each `MODEL_*` variable can use a different provider. `MODEL` is the fallback for unrecognized Claude models.+Start LM Studio's local server, load a model, then configure:```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+LM_STUDIO_BASE_URL="http://localhost:1234/v1"+MODEL="lmstudio/your-loaded-model"```-</details>+Use the model identifier shown by LM Studio. Prefer models with tool-use support for Claude Code workflows.-> 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.+</details><details>-<summary><b>Optional Authentication</b> (restrict access to your proxy)</summary>+<summary><b>llama.cpp</b></summary>-Set `ANTHROPIC_AUTH_TOKEN` in `.env` to require clients to authenticate:+Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests.```dotenv-ANTHROPIC_AUTH_TOKEN="your-secret-token-here"+LLAMACPP_BASE_URL="http://localhost:8080/v1"+MODEL="llamacpp/local-model"```-**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+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.++</details>++<details>+<summary><b>Ollama</b></summary>++Run Ollama and pull a model:-**Example usage:**```bash-# With authentication-ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \-ANTHROPIC_BASE_URL="http://localhost:8082" claude+ollama pull llama3.1+ollama serve+```-# claude-pick automatically uses the configured token-claude-pick+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 this feature if:-- Running the proxy on a public network-- Sharing the server with others but restricting access-- Wanting an additional layer of security+Use the same tag shown by `ollama list`, for example `ollama/llama3.1:8b`.</details>-### Run It+<details>+<summary><b>Mix providers by model tier</b></summary>-**Terminal 1:** Start the proxy server:+Each tier can use a different provider:-```bash-uv run uvicorn server:app --host 0.0.0.0 --port 8082+```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"```-**Terminal 2:** Run Claude Code:+</details>-Point `ANTHROPIC_BASE_URL` at the proxy root URL, not `http://localhost:8082/v1`.+## Connect Claude Code++### Claude Code CLI-#### Powershell-```powershell-$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude-```-#### Bash```bashANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude```-That's it! Claude Code now uses your configured provider for free.--<details>-<summary><b>VSCode Extension Setup</b></summary>+### VS Code Extension-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:+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-</details>---<details>-<summary><b>IntelliJ Extension Setup</b></summary>--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+Edit the installed Claude ACP config:-</details>--<details>-<summary><b>Multi-Model Support (Model Picker)</b></summary>+- Windows: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json`+- Linux/macOS: `~/.jetbrains/acp.json`-`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`.+Set the environment for `acp.registry.claude-acp`:-https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645+```json+"env": {+ "ANTHROPIC_BASE_URL": "http://localhost:8082",+ "ANTHROPIC_AUTH_TOKEN": "freecc"+}+```-**1. Install [fzf](https://github.com/junegunn/fzf)**:+Restart the IDE after changing the file.-```bash-brew install fzf # macOS/Linux-```+### Model Picker-**2. Add the alias to `~/.zshrc` or `~/.bashrc`:**+`claude-pick` lets you choose a model at launch time.```bash+brew install fzfalias 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:```bashalias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude'```-</details>+## 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:+Discord minimum config:-```bash-free-claude-code # starts the server+```dotenv+MESSAGING_PLATFORM="discord"+DISCORD_BOT_TOKEN="your-discord-bot-token"+ALLOWED_DISCORD_CHANNELS="123456789"+CLAUDE_WORKSPACE="./agent_workspace"+ALLOWED_DIR="C:/Users/yourname/projects"```-> To update: `uv tool upgrade free-claude-code`-----+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.-## How It Works+Telegram minimum config:+```dotenv+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"```-┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐-│ 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**: `<think>` 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` |--<details>-<summary><b>NVIDIA NIM models</b></summary>--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`--</details>--<details>-<summary><b>OpenRouter models</b></summary>--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)--</details>-<details>-<summary><b>DeepSeek models</b></summary>--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)+Get a token from [@BotFather](https://t.me/BotFather) and your user ID from [@userinfobot](https://t.me/userinfobot).-</details>--<details>-<summary><b>LM Studio models</b></summary>+Useful commands:-Run models locally with [LM Studio](https://lmstudio.ai). Load a model in the Chat or Developer tab, then set `MODEL` to its identifier.+- `/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.-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)--</details>+### Voice Notes-<details>-<summary><b>llama.cpp models</b></summary>+Voice notes work on Discord and Telegram. Choose one backend:-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`.+```bash+uv sync --extra voice_local+uv sync --extra voice+uv sync --extra voice --extra voice_local+```-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)+```dotenv+VOICE_NOTE_ENABLED=true+WHISPER_DEVICE="cpu" # cpu | cuda | nvidia_nim+WHISPER_MODEL="base"+HF_TOKEN=""+```-</details>+Use `WHISPER_DEVICE="nvidia_nim"` with the `voice` extra and `NVIDIA_NIM_API_KEY` for NVIDIA-hosted transcription.-<details>-<summary><b>Ollama models</b></summary>+## Configuration Reference-Run models locally with [Ollama](https://ollama.com). Pull a model, then set `MODEL` to `ollama/<tag>` where `<tag>` matches the name in `ollama list` (for example `ollama/llama3.1:8b` or `ollama/qwen2.5-coder:7b`).+[`.env.example`](.env.example) is the canonical list of variables. The sections below are the ones most users change.-- `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.+### Model Routing-```bash-ollama pull llama3.1-ollama serve # or use the desktop app, which keeps the server running+```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=```-Browse: [ollama.com/library](https://ollama.com/library)+Blank per-tier values inherit the fallback. Blank thinking overrides inherit `ENABLE_MODEL_THINKING`.-</details>+### Provider Keys And URLs------## Discord Bot+```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"+```-Control Claude Code remotely from Discord (or Telegram). Send tasks, watch live progress, and manage multiple concurrent sessions.+Proxy settings are per provider:-**Capabilities:**+```dotenv+NVIDIA_NIM_PROXY=""+OPENROUTER_PROXY=""+LMSTUDIO_PROXY=""+LLAMACPP_PROXY=""+```-- 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`+### Rate Limits And Timeouts-### Setup+```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+```-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.+Use lower limits for free hosted providers; local providers can usually tolerate higher concurrency if the machine can handle it.-2. **Edit `.env`:**+### Security And Diagnostics```dotenv-MESSAGING_PLATFORM="discord"-DISCORD_BOT_TOKEN="your_discord_bot_token"-ALLOWED_DISCORD_CHANNELS="123456789,987654321"+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```-> 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.+Raw logging flags can expose prompts, tool arguments, paths, and model output. Keep them off unless you are debugging locally.-3. **Configure the workspace** (where Claude will operate):+### Local Web Tools```dotenv-CLAUDE_WORKSPACE="./agent_workspace"-ALLOWED_DIR="C:/Users/yourname/projects"+ENABLE_WEB_SERVER_TOOLS=true+WEB_FETCH_ALLOWED_SCHEMES=http,https+WEB_FETCH_ALLOW_PRIVATE_NETWORKS=false```-4. **Start the server:**+These tools perform outbound HTTP from the proxy. Keep private-network access disabled unless you are in a controlled lab environment.-```bash-uv run uvicorn server:app --host 0.0.0.0 --port 8082-```+## Troubleshooting-5. **Invite the bot** via OAuth2 URL Generator (scopes: `bot`, permissions: Read Messages, Send Messages, Manage Messages, Read Message History).+### Claude Code says `undefined ... input_tokens`, `$.speed`, or malformed response-### Telegram+Update to the latest commit first. Older versions could emit invalid usage metadata in streaming responses. Then check:-Set `MESSAGING_PLATFORM=telegram` and configure:+- `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.-```dotenv-TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"-ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id"-```+### llama.cpp or LM Studio returns HTTP 400-Get a token from [@BotFather](https://t.me/BotFather); find your user ID via [@userinfobot](https://t.me/userinfobot).+This usually means the local runtime rejected the Anthropic Messages request before the proxy could stream a model answer.-### Voice Notes+Check:-Send voice messages on Discord or Telegram; they are transcribed and processed as regular prompts.+- 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.-| 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` |+### Provider disconnects during streaming-**Install the voice extras:**+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.-```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"-```--Configure via `WHISPER_DEVICE` (`cpu` | `cuda` | `nvidia_nim`) and `WHISPER_MODEL`. See the [Configuration](#configuration) table for all voice variables and supported model values.-------## Configuration--### Core--| 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` |--### Rate Limiting & Timeouts--| 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` |--### Messaging & Voice--| 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) | — |+### Tool calls work on one model but not another-<details>-<summary><b>Advanced: Request optimization flags</b></summary>+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.-These are enabled by default and intercept trivial Claude Code requests locally to save API quota.+### The VS Code extension still shows a login screen-| 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` |+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.-</details>+## How It Works-See [`.env.example`](.env.example) for all supported parameters.+```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-```+```textfree-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```-### Extending+Run them in that order before pushing. CI enforces the same checks.-**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)-```+### Package Scripts-**Adding a native Anthropic provider** — extend `AnthropicMessagesTransport`, then add a descriptor in `providers.registry`.+`pyproject.toml` installs:-**Adding a fully custom provider** — extend `BaseProvider` directly, implement `stream_response()`, and register its descriptor.+- `free-claude-code`: starts the proxy with configured host and port.+- `fcc-init`: creates the user config template at `~/.config/free-claude-code/.env`.-**Adding a messaging platform** — extend `MessagingPlatform` in `messaging/` and implement `start()`, `stop()`, `send_message()`, `edit_message()`, and `on_message()`.+### Extending----+- 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.## LicenseMIT 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/).