Skip to content
Back to search

free-claude-code

SkillWorks with Claude CodeGitHub

Use claude-code for free in the terminal, VSCode extension or via discord like openclaw

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codeaashu--free-claude-code/badge.svg)](/listings/codeaashu--free-claude-code)

HTML

<a href="/listings/codeaashu--free-claude-code"><img src="/api/listings/codeaashu--free-claude-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

1. Get an API key (or use LM Studio / llama.cpp locally): - **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. 2. Install [Claude Code](https://github.com/anthropics/claude-code)

Install `uv`

# Install uv (required to run the project)
pip install uv

If uv is already installed, run uv self update to get the latest version.

Clone & Configure

git clone https://github.com/codeaashu/free-claude-code.git
cd free-claude-code
cp .env.example .env

Choose your provider and edit `.env`:

<details> <summary><b>NVIDIA NIM</b> (40 req/min free, recommended)</summary>

NVIDIA_NIM_API_KEY="nvapi-your-key-here"

MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
MODEL="nvidia_nim/z-ai/glm4.7"                     # fallback

# Global switch for provider reasoning requests and Claude thinking blocks.
ENABLE_THINKING=true

</details>

<details> <summary><b>OpenRouter</b> (hundreds of models)</summary>

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

</details>

<details> <summary><b>DeepSeek</b> (direct API)</summary>

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

</details>

<details> <summary><b>LM Studio</b> (fully local, no API key)</summary>

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

</details>

<details> <summary><b>llama.cpp</b> (fully local, no API key)</summary>

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"

</details>

<details> <summary><b>Mix providers</b></summary>

Each `MODEL_*` variable can use a different provider. `MODEL` is the fallback for unrecognized Claude models.

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

</details>

> Migration: `NIM_ENABLE_THINKING` was removed in this release. Rename it to `ENABLE_THINKING`.

<details> <summary><b>Optional Authentication</b> (restrict access to your proxy)</summary>

Set `ANTHROPIC_AUTH_TOKEN` in `.env` to require clients to authenticate:

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:**

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 649 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🤖 Free Claude Code
  3. ### Use Claude Code CLI & VSCode for free. No Anthropic API key required.
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
  5. [![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/)
  6. [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge)](https://github.com/astral-sh/uv)
  7. [![Tested with Pytest](https://img.shields.io/badge/testing-Pytest-00c0ff.svg?style=for-the-badge)](https://github.com/codeaashu/free-claude-code/actions/workflows/tests.yml)
  8. [![Type checking: Ty](https://img.shields.io/badge/type%20checking-ty-ffcc00.svg?style=for-the-badge)](https://pypi.org/project/ty/)
  9. [![Code style: Ruff](https://img.shields.io/badge/code%20formatting-ruff-f5a623.svg?style=for-the-badge)](https://github.com/astral-sh/ruff)
  10. [![Logging: Loguru](https://img.shields.io/badge/logging-loguru-4ecdc4.svg?style=for-the-badge)](https://github.com/Delgan/loguru)
  11. [![Twitter Follow](https://img.shields.io/twitter/follow/warrioraashuu?style=social)](https://twitter.com/intent/follow?screen_name=warrioraashuu)
  12. A lightweight proxy that routes Claude Code's Anthropic API calls to **NVIDIA NIM** (40 req/min free), **OpenRouter** (hundreds of models), **DeepSeek** (direct API), **LM Studio** (fully local), or **llama.cpp** (local with Anthropic endpoints).
  13. [Quick Start](#quick-start) · [Providers](#providers) · [Discord Bot](#discord-bot) · [Configuration](#configuration) · [Development](#development) · [Contributing](#contributing)
  14. ---
  15. </div>
  16. <div align="center">
  17. <img src="pic.png" alt="Free Claude Code in action" width="700">
  18. <p><em>Claude Code running via NVIDIA NIM, completely free</em></p>
  19. </div>
  20. ## Features
  21. | Feature | Description |
  22. | -------------------------- | ----------------------------------------------------------------------------------------------- |
  23. | **Zero Cost** | 40 req/min free on NVIDIA NIM. Free models on OpenRouter. Fully local with LM Studio |
  24. | **Drop-in Replacement** | Set 2 env vars. No modifications to Claude Code CLI or VSCode extension needed |
  25. | **5 Providers** | NVIDIA NIM, OpenRouter, DeepSeek, LM Studio (local), llama.cpp (`llama-server`) |
  26. | **Per-Model Mapping** | Route Opus / Sonnet / Haiku to different models and providers. Mix providers freely |
  27. | **Thinking Token Support** | Parses `<think>` tags and `reasoning_content` into native Claude thinking blocks |
  28. | **Heuristic Tool Parser** | Models outputting tool calls as text are auto-parsed into structured tool use |
  29. | **Request Optimization** | 5 categories of trivial API calls intercepted locally, saving quota and latency |
  30. | **Smart Rate Limiting** | Proactive rolling-window throttle + reactive 429 exponential backoff + optional concurrency cap |
  31. | **Discord / Telegram Bot** | Remote autonomous coding with tree-based threading, session persistence, and live progress |
  32. | **Subagent Control** | Task tool interception forces `run_in_background=False`. No runaway subagents |
  33. | **Extensible** | Clean `BaseProvider` and `MessagingPlatform` ABCs. Add new providers or platforms easily |
  34. ## Quick Start
  35. ### Prerequisites
  36. 1. Get an API key (or use LM Studio / llama.cpp locally):
  37. - **NVIDIA NIM**: [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys)
  38. - **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys)
  39. - **DeepSeek**: [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)
  40. - **LM Studio**: No API key needed. Run locally with [LM Studio](https://lmstudio.ai)
  41. - **llama.cpp**: No API key needed. Run `llama-server` locally.
  42. 2. Install [Claude Code](https://github.com/anthropics/claude-code)
  43. ### Install `uv`
  44. ```bash
  45. # Install uv (required to run the project)
  46. pip install uv
  47. ```
  48. If uv is already installed, run uv self update to get the latest version.
  49. ### Clone & Configure
  50. ```bash
  51. git clone https://github.com/codeaashu/free-claude-code.git
  52. cd free-claude-code
  53. cp .env.example .env
  54. ```
  55. Choose your provider and edit `.env`:
  56. <details>
  57. <summary><b>NVIDIA NIM</b> (40 req/min free, recommended)</summary>
  58. ```dotenv
  59. NVIDIA_NIM_API_KEY="nvapi-your-key-here"
  60. MODEL_OPUS=
  61. MODEL_SONNET=
  62. MODEL_HAIKU=
  63. MODEL="nvidia_nim/z-ai/glm4.7" # fallback
  64. # Global switch for provider reasoning requests and Claude thinking blocks.
  65. ENABLE_THINKING=true
  66. ```
  67. </details>
  68. <details>
  69. <summary><b>OpenRouter</b> (hundreds of models)</summary>
  70. ```dotenv
  71. OPENROUTER_API_KEY="sk-or-your-key-here"
  72. MODEL_OPUS="open_router/deepseek/deepseek-r1-0528:free"
  73. MODEL_SONNET="open_router/openai/gpt-oss-120b:free"
  74. MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"
  75. MODEL="open_router/stepfun/step-3.5-flash:free" # fallback
  76. ```
  77. </details>
  78. <details>
  79. <summary><b>DeepSeek</b> (direct API)</summary>
  80. ```dotenv
  81. DEEPSEEK_API_KEY="your-deepseek-key-here"
  82. MODEL_OPUS="deepseek/deepseek-reasoner"
  83. MODEL_SONNET="deepseek/deepseek-chat"
  84. MODEL_HAIKU="deepseek/deepseek-chat"
  85. MODEL="deepseek/deepseek-chat" # fallback
  86. ```
  87. </details>
  88. <details>
  89. <summary><b>LM Studio</b> (fully local, no API key)</summary>
  90. ```dotenv
  91. MODEL_OPUS="lmstudio/unsloth/MiniMax-M2.5-GGUF"
  92. MODEL_SONNET="lmstudio/unsloth/Qwen3.5-35B-A3B-GGUF"
  93. MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
  94. MODEL="lmstudio/unsloth/GLM-4.7-Flash-GGUF" # fallback
  95. ```
  96. </details>
  97. <details>
  98. <summary><b>llama.cpp</b> (fully local, no API key)</summary>
  99. ```dotenv
  100. LLAMACPP_BASE_URL="http://localhost:8080/v1"
  101. MODEL_OPUS="llamacpp/local-model"
  102. MODEL_SONNET="llamacpp/local-model"
  103. MODEL_HAIKU="llamacpp/local-model"
  104. MODEL="llamacpp/local-model"
  105. ```
  106. </details>
  107. <details>
  108. <summary><b>Mix providers</b></summary>
  109. Each `MODEL_*` variable can use a different provider. `MODEL` is the fallback for unrecognized Claude models.
  110. ```dotenv
  111. NVIDIA_NIM_API_KEY="nvapi-your-key-here"
  112. OPENROUTER_API_KEY="sk-or-your-key-here"
  113. MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"
  114. MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free"
  115. MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
  116. MODEL="nvidia_nim/z-ai/glm4.7" # fallback
  117. ```
  118. </details>
  119. > Migration: `NIM_ENABLE_THINKING` was removed in this release. Rename it to `ENABLE_THINKING`.
  120. <details>
  121. <summary><b>Optional Authentication</b> (restrict access to your proxy)</summary>
  122. Set `ANTHROPIC_AUTH_TOKEN` in `.env` to require clients to authenticate:
  123. ```dotenv
  124. ANTHROPIC_AUTH_TOKEN="your-secret-token-here"
  125. ```
  126. **How it works:**
  127. - If `ANTHROPIC_AUTH_TOKEN` is empty (default), no authentication is required (backward compatible)
  128. - If set, clients must provide the same token via the `ANTHROPIC_AUTH_TOKEN` header
  129. - The `claude-pick` script automatically reads the token from `.env` if configured
  130. **Example usage:**
  131. ```bash
  132. # With authentication
  133. ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \
  134. ANTHROPIC_BASE_URL="http://localhost:8082" claude
  135. # claude-pick automatically uses the configured token
  136. claude-pick
  137. ```
  138. Use this feature if:
  139. - Running the proxy on a public network
  140. - Sharing the server with others but restricting access
  141. - Wanting an additional layer of security
  142. </details>
  143. ### Run It
  144. **Terminal 1:** Start the proxy server:
  145. ```bash
  146. uv run uvicorn server:app --host 0.0.0.0 --port 8082
  147. ```
  148. **Terminal 2:** Run Claude Code:
  149. Point `ANTHROPIC_BASE_URL` at the proxy root URL, not `http://localhost:8082/v1`.
  150. #### Powershell
  151. ```powershell
  152. $env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; claude
  153. ```
  154. #### Bash
  155. ```bash
  156. ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude
  157. ```
  158. That's it! Claude Code now uses your configured provider for free.
  159. <details>
  160. <summary><b>VSCode Extension Setup</b></summary>
  161. 1. Start the proxy server (same as above).
  162. 2. Open Settings (`Ctrl + ,`) and search for `claude-code.environmentVariables`.
  163. 3. Click **Edit in settings.json** and add:
  164. ```json
  165. "claudeCode.environmentVariables": [
  166. { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  167. { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
  168. ]
  169. ```
  170. 4. Reload extensions.
  171. 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.
  172. To switch back to Anthropic models, comment out the added block and reload extensions.
  173. </details>
  174. <details>
  175. <summary><b>IntelliJ Extension Setup</b></summary>
  176. 1. Open the configuration file:
  177. - **Windows**: `C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json`
  178. - **Linux/macOS**: `~/.jetbrains/acp.json`
  179. 2. Inside acp.registry.claude-acp, change:
  180. ```
  181. "env": {}
  182. ```
  183. to
  184. ```
  185. "env": {
  186. "ANTHROPIC_AUTH_TOKEN": "freecc",
  187. "ANTHROPIC_BASE_URL": "http://localhost:8082"
  188. }
  189. ```
  190. 3. Start the proxy server
  191. 4. Restart IDE
  192. </details>
  193. <details>
  194. <summary><b>Multi-Model Support (Model Picker)</b></summary>
  195. `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`.
  196. https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645
  197. **1. Install [fzf](https://github.com/junegunn/fzf)**:
  198. ```bash
  199. brew install fzf # macOS/Linux
  200. ```
  201. **2. Add the alias to `~/.zshrc` or `~/.bashrc`:**
  202. ```bash
  203. alias claude-pick="/absolute/path/to/free-claude-code/claude-pick"
  204. ```
  205. Then reload your shell (`source ~/.zshrc` or `source ~/.bashrc`) and run `claude-pick`.
  206. **Or use a fixed model alias** (no picker needed):
  207. ```bash
  208. alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude'
  209. ```
  210. </details>
  211. ### Install as a Package (no clone needed)
  212. ```bash
  213. uv tool install git+https://github.com/codeaashu/free-claude-code.git
  214. fcc-init # creates ~/.config/free-claude-code/.env from the built-in template
  215. ```
  216. Edit `~/.config/free-claude-code/.env` with your API keys and model names, then:
  217. ```bash
  218. free-claude-code # starts the server
  219. ```
  220. > To update: `uv tool upgrade free-claude-code`
  221. ---
  222. ## How It Works
  223. ```
  224. ┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐
  225. │ Claude Code │───────>│ Free Claude Code │───────>│ LLM Provider │
  226. │ CLI / VSCode │<───────│ Proxy (:8082) │<───────│ NIM / OR / LMS │
  227. └─────────────────┘ └──────────────────────┘ └──────────────────┘
  228. Anthropic API Native Anthropic
  229. format (SSE) or OpenAI chat SSE
  230. ```
  231. - **Transparent proxy**: Claude Code sends standard Anthropic API requests; the proxy forwards them to your configured provider
  232. - **Per-model routing**: Opus / Sonnet / Haiku requests resolve to their model-specific backend, with `MODEL` as fallback
  233. - **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
  234. - **Format handling**: OpenRouter, LM Studio, and llama.cpp use native Anthropic Messages endpoints; NIM and DeepSeek use shared OpenAI chat translation
  235. - **Thinking tokens**: `<think>` tags and `reasoning_content` fields are converted into native Claude thinking blocks when `ENABLE_THINKING=true`
  236. 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.
  237. ---
  238. ## Providers
  239. | Provider | Cost | Rate Limit | Best For |
  240. | -------------- | ------------ | ---------- | ------------------------------------ |
  241. | **NVIDIA NIM** | Free | 40 req/min | Daily driver, generous free tier |
  242. | **OpenRouter** | Free / Paid | Varies | Model variety, fallback options |
  243. | **DeepSeek** | Usage-based | Varies | Direct access to DeepSeek chat/reasoner |
  244. | **LM Studio** | Free (local) | Unlimited | Privacy, offline use, no rate limits |
  245. | **llama.cpp** | Free (local) | Unlimited | Lightweight local inference engine |
  246. Models use a prefix format: `provider_prefix/model/name`. An invalid prefix causes an error.
  247. | Provider | `MODEL` prefix | API Key Variable | Default Base URL |
  248. | ---------- | ----------------- | -------------------- | ----------------------------- |
  249. | NVIDIA NIM | `nvidia_nim/...` | `NVIDIA_NIM_API_KEY` | `integrate.api.nvidia.com/v1` |
  250. | OpenRouter | `open_router/...` | `OPENROUTER_API_KEY` | `openrouter.ai/api/v1` |
  251. | DeepSeek | `deepseek/...` | `DEEPSEEK_API_KEY` | `api.deepseek.com` |
  252. | LM Studio | `lmstudio/...` | (none) | `localhost:1234/v1` |
  253. | llama.cpp | `llamacpp/...` | (none) | `localhost:8080/v1` |
  254. <details>
  255. <summary><b>NVIDIA NIM models</b></summary>
  256. Popular models (full list in [`nvidia_nim_models.json`](nvidia_nim_models.json)):
  257. - `nvidia_nim/minimaxai/minimax-m2.5`
  258. - `nvidia_nim/qwen/qwen3.5-397b-a17b`
  259. - `nvidia_nim/z-ai/glm5`
  260. - `nvidia_nim/moonshotai/kimi-k2.5`
  261. - `nvidia_nim/stepfun-ai/step-3.5-flash`
  262. Browse: [build.nvidia.com](https://build.nvidia.com/explore/discover) · Update list: `curl "https://integrate.api.nvidia.com/v1/models" > nvidia_nim_models.json`
  263. </details>
  264. <details>
  265. <summary><b>OpenRouter models</b></summary>
  266. Popular free models:
  267. - `open_router/arcee-ai/trinity-large-preview:free`
  268. - `open_router/stepfun/step-3.5-flash:free`
  269. - `open_router/deepseek/deepseek-r1-0528:free`
  270. - `open_router/openai/gpt-oss-120b:free`
  271. Browse: [openrouter.ai/models](https://openrouter.ai/models) · [Free models](https://openrouter.ai/collections/free-models)
  272. </details>
  273. <details>
  274. <summary><b>DeepSeek models</b></summary>
  275. DeepSeek currently exposes the direct API models:
  276. - `deepseek/deepseek-chat`
  277. - `deepseek/deepseek-reasoner`
  278. Browse: [api-docs.deepseek.com](https://api-docs.deepseek.com)
  279. </details>
  280. <details>
  281. <summary><b>LM Studio models</b></summary>
  282. Run models locally with [LM Studio](https://lmstudio.ai). Load a model in the Chat or Developer tab, then set `MODEL` to its identifier.
  283. Examples with native tool-use support:
  284. - `LiquidAI/LFM2-24B-A2B-GGUF`
  285. - `unsloth/MiniMax-M2.5-GGUF`
  286. - `unsloth/GLM-4.7-Flash-GGUF`
  287. - `unsloth/Qwen3.5-35B-A3B-GGUF`
  288. Browse: [model.lmstudio.ai](https://model.lmstudio.ai)
  289. </details>
  290. <details>
  291. <summary><b>llama.cpp models</b></summary>
  292. 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`.
  293. See the Unsloth docs for detailed instructions and capable models:
  294. [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)
  295. </details>
  296. ---
  297. ## Discord Bot
  298. Control Claude Code remotely from Discord (or Telegram). Send tasks, watch live progress, and manage multiple concurrent sessions.
  299. **Capabilities:**
  300. - Tree-based message threading: reply to a message to fork the conversation
  301. - Session persistence across server restarts
  302. - Live streaming of thinking tokens, tool calls, and results
  303. - Unlimited concurrent Claude CLI sessions (concurrency controlled by `PROVIDER_MAX_CONCURRENCY`)
  304. - Voice notes: send voice messages; they are transcribed and processed as regular prompts
  305. - 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`
  306. ### Setup
  307. 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.
  308. 2. **Edit `.env`:**
  309. ```dotenv
  310. MESSAGING_PLATFORM="discord"
  311. DISCORD_BOT_TOKEN="your_discord_bot_token"
  312. ALLOWED_DISCORD_CHANNELS="123456789,987654321"
  313. ```
  314. > 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.
  315. 3. **Configure the workspace** (where Claude will operate):
  316. ```dotenv
  317. CLAUDE_WORKSPACE="./agent_workspace"
  318. ALLOWED_DIR="C:/Users/yourname/projects"
  319. ```
  320. 4. **Start the server:**
  321. ```bash
  322. uv run uvicorn server:app --host 0.0.0.0 --port 8082
  323. ```
  324. 5. **Invite the bot** via OAuth2 URL Generator (scopes: `bot`, permissions: Read Messages, Send Messages, Manage Messages, Read Message History).
  325. ### Telegram
  326. Set `MESSAGING_PLATFORM=telegram` and configure:
  327. ```dotenv
  328. TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
  329. ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id"
  330. ```
  331. Get a token from [@BotFather](https://t.me/BotFather); find your user ID via [@userinfobot](https://t.me/userinfobot).
  332. ### Voice Notes
  333. Send voice messages on Discord or Telegram; they are transcribed and processed as regular prompts.
  334. | Backend | Description | API Key |
  335. | --------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
  336. | **Local Whisper** (default) | [Hugging Face Whisper](https://huggingface.co/openai/whisper-large-v3-turbo) — free, offline, CUDA compatible | not required |
  337. | **NVIDIA NIM** | Whisper/Parakeet models via gRPC | `NVIDIA_NIM_API_KEY` |
  338. **Install the voice extras:**
  339. ```bash
  340. # If you cloned the repo:
  341. uv sync --extra voice_local # Local Whisper
  342. uv sync --extra voice # NVIDIA NIM
  343. uv sync --extra voice --extra voice_local # Both
  344. # If you installed as a package (no clone):
  345. uv tool install "free-claude-code[voice_local] @ git+https://github.com/codeaashu/free-claude-code.git"
  346. uv tool install "free-claude-code[voice] @ git+https://github.com/codeaashu/free-claude-code.git"
  347. uv tool install "free-claude-code[voice,voice_local] @ git+https://github.com/codeaashu/free-claude-code.git"
  348. ```
  349. Configure via `WHISPER_DEVICE` (`cpu` | `cuda` | `nvidia_nim`) and `WHISPER_MODEL`. See the [Configuration](#configuration) table for all voice variables and supported model values.
  350. ---
  351. ## Configuration
  352. ### Core
  353. | Variable | Description | Default |
  354. | -------------------- | --------------------------------------------------------------------- | ------------------------------------------------- |
  355. | `MODEL` | Fallback model (`provider/model/name` format; invalid prefix → error) | `nvidia_nim/z-ai/glm4.7` |
  356. | `MODEL_OPUS` | Model for Claude Opus requests; empty falls back to `MODEL` | empty |
  357. | `MODEL_SONNET` | Model for Claude Sonnet requests; empty falls back to `MODEL` | empty |
  358. | `MODEL_HAIKU` | Model for Claude Haiku requests; empty falls back to `MODEL` | empty |
  359. | `NVIDIA_NIM_API_KEY` | NVIDIA API key | required for NIM |
  360. | `ENABLE_THINKING` | Global switch for provider reasoning requests and Claude thinking blocks. Set `false` to hide thinking across all providers. | `true` |
  361. | `OPENROUTER_API_KEY` | OpenRouter API key | required for OpenRouter |
  362. | `DEEPSEEK_API_KEY` | DeepSeek API key | required for DeepSeek |
  363. | `LM_STUDIO_BASE_URL` | LM Studio server URL | `http://localhost:1234/v1` |
  364. | `LLAMACPP_BASE_URL` | llama.cpp server URL | `http://localhost:8080/v1` |
  365. | `NVIDIA_NIM_PROXY` | Optional proxy URL for NVIDIA NIM requests (`http://...` or `socks5://...`) | `""` |
  366. | `OPENROUTER_PROXY` | Optional proxy URL for OpenRouter requests (`http://...` or `socks5://...`) | `""` |
  367. | `LMSTUDIO_PROXY` | Optional proxy URL for LM Studio requests (`http://...` or `socks5://...`) | `""` |
  368. | `LLAMACPP_PROXY` | Optional proxy URL for llama.cpp requests (`http://...` or `socks5://...`) | `""` |
  369. ### Rate Limiting & Timeouts
  370. | Variable | Description | Default |
  371. | -------------------------- | ----------------------------------------- | ------- |
  372. | `PROVIDER_RATE_LIMIT` | LLM API requests per window | `40` |
  373. | `PROVIDER_RATE_WINDOW` | Rate limit window (seconds) | `60` |
  374. | `PROVIDER_MAX_CONCURRENCY` | Max simultaneous open provider streams | `5` |
  375. | `HTTP_READ_TIMEOUT` | Read timeout for provider requests (s) | `120` |
  376. | `HTTP_WRITE_TIMEOUT` | Write timeout for provider requests (s) | `10` |
  377. | `HTTP_CONNECT_TIMEOUT` | Connect timeout for provider requests (s) | `10` |
  378. ### Messaging & Voice
  379. | Variable | Description | Default |
  380. | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
  381. | `MESSAGING_PLATFORM` | `discord` or `telegram` | `discord` |
  382. | `DISCORD_BOT_TOKEN` | Discord bot token | `""` |
  383. | `ALLOWED_DISCORD_CHANNELS` | Comma-separated channel IDs (empty = none allowed) | `""` |
  384. | `TELEGRAM_BOT_TOKEN` | Telegram bot token | `""` |
  385. | `ALLOWED_TELEGRAM_USER_ID` | Allowed Telegram user ID | `""` |
  386. | `CLAUDE_WORKSPACE` | Directory where the agent operates | `./agent_workspace` |
  387. | `ALLOWED_DIR` | Allowed directories for the agent | `""` |
  388. | `MESSAGING_RATE_LIMIT` | Messaging messages per window | `1` |
  389. | `MESSAGING_RATE_WINDOW` | Messaging window (seconds) | `1` |
  390. | `VOICE_NOTE_ENABLED` | Enable voice note handling | `true` |
  391. | `WHISPER_DEVICE` | `cpu` \| `cuda` \| `nvidia_nim` | `cpu` |
  392. | `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` |
  393. | `HF_TOKEN` | Hugging Face token for faster downloads (local Whisper, optional) | — |
  394. <details>
  395. <summary><b>Advanced: Request optimization flags</b></summary>
  396. These are enabled by default and intercept trivial Claude Code requests locally to save API quota.
  397. | Variable | Description | Default |
  398. | --------------------------------- | ------------------------------ | ------- |
  399. | `FAST_PREFIX_DETECTION` | Enable fast prefix detection | `true` |
  400. | `ENABLE_NETWORK_PROBE_MOCK` | Mock network probe requests | `true` |
  401. | `ENABLE_TITLE_GENERATION_SKIP` | Skip title generation requests | `true` |
  402. | `ENABLE_SUGGESTION_MODE_SKIP` | Skip suggestion mode requests | `true` |
  403. | `ENABLE_FILEPATH_EXTRACTION_MOCK` | Mock filepath extraction | `true` |
  404. </details>
  405. See [`.env.example`](.env.example) for all supported parameters.
  406. ---
  407. ## Development
  408. ### Project Structure
  409. ```
  410. free-claude-code/
  411. ├── server.py # Entry point
  412. ├── api/ # FastAPI routes, API service layer, model routing, request detection, optimizations
  413. ├── core/ # Shared Anthropic protocol helpers, SSE, conversion, parsers, token counting
  414. ├── providers/ # Provider registry, scoped runtime state, OpenAI chat + Anthropic messages transports
  415. ├── messaging/ # MessagingPlatform ABC + Discord/Telegram bots, commands, voice, session management
  416. ├── config/ # Settings, NIM config, logging
  417. ├── cli/ # CLI session and process management
  418. └── tests/ # Pytest test suite
  419. ```
  420. ### Commands
  421. ```bash
  422. uv run ruff format # Format code
  423. uv run ruff check # Lint
  424. uv run ty check # Type checking
  425. uv run pytest # Run tests
  426. ```
  427. ### Extending
  428. **Adding an OpenAI-compatible provider** (Groq, Together AI, etc.) — extend `OpenAIChatTransport`, then add a descriptor in the provider registry:
  429. ```python
  430. from providers.openai_compat import OpenAIChatTransport
  431. from providers.base import ProviderConfig
  432. class MyProvider(OpenAIChatTransport):
  433. def __init__(self, config: ProviderConfig):
  434. super().__init__(config, provider_name="MYPROVIDER",
  435. base_url="https://api.example.com/v1", api_key=config.api_key)
  436. ```
  437. **Adding a native Anthropic provider** — extend `AnthropicMessagesTransport`, then add a descriptor in `providers.registry`.
  438. **Adding a fully custom provider** — extend `BaseProvider` directly, implement `stream_response()`, and register its descriptor.
  439. **Adding a messaging platform** — extend `MessagingPlatform` in `messaging/` and implement `start()`, `stop()`, `send_message()`, `edit_message()`, and `on_message()`.
  440. ---
  441. ## Contributing
  442. - Report bugs or suggest features via [Issues](https://github.com/codeaashu/free-claude-code/issues)
  443. - Add new LLM providers (Groq, Together AI, etc.)
  444. - Add new messaging platforms (Slack, etc.)
  445. - Improve test coverage
  446. - Not accepting Docker integration PRs for now
  447. ```bash
  448. git checkout -b my-feature
  449. uv run ruff format && uv run ruff check && uv run ty check && uv run pytest
  450. # Open a pull request
  451. ```
  452. ---
  453. ## License
  454. MIT License. See [LICENSE](LICENSE) for details.
  455. 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/).
  456. ---
  457. Cooked by aashuu ✦ (Ashutosh Kumar)<br>
  458. Founder of [2C Labs](https://www.2clabs.tech)
  459. I build tech businesses through SaaS products across every layer of the internet ( Web2 ▪︎ Web3 ▪︎ AI-native ▪︎ Infrastructure )
  460. Connect here:<br>
  461. Website [www.aashuu.me](https://www.aashuu.me) ✦ 𝕏 [@warrioraashuu](https://x.com/warrioraashuu) ✦ LinkedIn [@warrioraashuu](https://www.linkedin.com/in/warrioraashuu/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.