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
Add option for an installable package (#75)
Ali Khokharc5341ecbbe8d
diff --git a/README.md b/README.mdindex 7a8c1b0a..434d06c1 100644--- a/README.md+++ b/README.md@@ -14,7 +14,7 @@A lightweight proxy that routes Claude Code's Anthropic API calls to **NVIDIA NIM** (40 req/min free), **OpenRouter** (hundreds of models), or **LM Studio** (fully local).-[Features](#features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Discord Bot](#discord-bot) · [Configuration](#configuration)+[Features](#features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Discord Bot](#discord-bot) · [Configuration](#configuration) · [Development](#development)---@@ -187,6 +187,23 @@ alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOK</details>+### Install as a Package (no clone needed)++If you just want to use the proxy without cloning the repo, install it as a `uv` tool:++```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+```++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 Worksdiff --git a/cli/entrypoints.py b/cli/entrypoints.pynew file mode 100644index 00000000..92f54e1d--- /dev/null+++ b/cli/entrypoints.py@@ -0,0 +1,47 @@+"""CLI entry points for the installed package."""++from __future__ import annotations+++def serve() -> None:+ """Start the FastAPI server (registered as `free-claude-code` script)."""+ import uvicorn++ from cli.process_registry import kill_all_best_effort+ from config.settings import get_settings++ settings = get_settings()+ try:+ uvicorn.run(+ "api.app:app",+ host=settings.host,+ port=settings.port,+ log_level="debug",+ timeout_graceful_shutdown=5,+ )+ finally:+ kill_all_best_effort()+++def init() -> None:+ """Scaffold config at ~/.config/free-claude-code/.env (registered as `fcc-init`)."""+ import importlib.resources+ from pathlib import Path++ config_dir = Path.home() / ".config" / "free-claude-code"+ env_file = config_dir / ".env"++ if env_file.exists():+ print(f"Config already exists at {env_file}")+ print("Delete it first if you want to reset to defaults.")+ return++ config_dir.mkdir(parents=True, exist_ok=True)+ template = (+ importlib.resources.files("config").joinpath("env.example").read_text("utf-8")+ )+ env_file.write_text(template, encoding="utf-8")+ print(f"Config created at {env_file}")+ print(+ "Edit it to set your API keys and model preferences, then run: free-claude-code"+ )diff --git a/config/env.example b/config/env.examplenew file mode 100644index 00000000..8965e367--- /dev/null+++ b/config/env.example@@ -0,0 +1,71 @@+# NVIDIA NIM Config+NVIDIA_NIM_API_KEY=""+++# OpenRouter Config+OPENROUTER_API_KEY=""+++# LM Studio Config (local provider, no API key required)+LM_STUDIO_BASE_URL="http://localhost:1234/v1"+++# All Claude model requests are mapped to these models, plain model is fallback+# Format: provider_type/model/name+# Valid providers: "nvidia_nim" | "open_router" | "lmstudio"+MODEL_OPUS="nvidia_nim/z-ai/glm4.7"+MODEL_SONNET="open_router/arcee-ai/trinity-large-preview:free"+MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"+MODEL="nvidia_nim/z-ai/glm4.7"+++# Provider config+PROVIDER_RATE_LIMIT=40+PROVIDER_RATE_WINDOW=60+PROVIDER_MAX_CONCURRENCY=5+++# HTTP client timeouts (seconds) for provider API requests+HTTP_READ_TIMEOUT=120+HTTP_WRITE_TIMEOUT=10+HTTP_CONNECT_TIMEOUT=2+++# Messaging Platform: "telegram" | "discord"+MESSAGING_PLATFORM="discord"+MESSAGING_RATE_LIMIT=1+MESSAGING_RATE_WINDOW=1+++# Voice Note Transcription+VOICE_NOTE_ENABLED=false+# WHISPER_DEVICE: "cpu" | "cuda" | "nvidia_nim"+# - "cpu"/"cuda": Hugging Face transformers Whisper (offline, free; install with: uv sync --extra voice_local)+# - "nvidia_nim": NVIDIA NIM Whisper via Riva gRPC (requires NVIDIA_NIM_API_KEY; install with: uv sync --extra voice)+WHISPER_DEVICE="nvidia_nim"+# WHISPER_MODEL:+# - For cpu/cuda: Hugging Face ID or short name (tiny, base, small, medium, large-v2, large-v3, large-v3-turbo)+# - For nvidia_nim: NVIDIA NIM model (e.g., "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3")+# - For nvidia_nim, default to "openai/whisper-large-v3" for best performance+WHISPER_MODEL="openai/whisper-large-v3"+HF_TOKEN=""+++# Telegram Config+TELEGRAM_BOT_TOKEN=""+ALLOWED_TELEGRAM_USER_ID=""+++# Discord Config+DISCORD_BOT_TOKEN=""+ALLOWED_DISCORD_CHANNELS=""+++# Agent Config+CLAUDE_WORKSPACE="./agent_workspace"+ALLOWED_DIR=""+FAST_PREFIX_DETECTION=true+ENABLE_NETWORK_PROBE_MOCK=true+ENABLE_TITLE_GENERATION_SKIP=true+ENABLE_SUGGESTION_MODE_SKIP=true+ENABLE_FILEPATH_EXTRACTION_MOCK=true\ No newline at end of filediff --git a/config/settings.py b/config/settings.pyindex cdff8f80..16bd7697 100644--- a/config/settings.py+++ b/config/settings.py@@ -1,6 +1,8 @@"""Centralized configuration using Pydantic Settings."""+import osfrom functools import lru_cache+from pathlib import Pathfrom pydantic import Field, field_validator, model_validatorfrom pydantic_settings import BaseSettings, SettingsConfigDict@@ -8,6 +10,17 @@ from pydantic_settings import BaseSettings, SettingsConfigDictfrom .nim import NimSettings+def _env_files() -> tuple[Path, ...]:+ """Return env file paths in priority order (later overrides earlier)."""+ files: list[Path] = [+ Path.home() / ".config" / "free-claude-code" / ".env",+ Path(".env"),+ ]+ if explicit := os.environ.get("FCC_ENV_FILE"):+ files.append(Path(explicit))+ return tuple(files)++class Settings(BaseSettings):"""Application settings loaded from environment variables."""@@ -196,7 +209,7 @@ class Settings(BaseSettings):return model_string.split("/", 1)[1]model_config = SettingsConfigDict(- env_file=".env",+ env_file=_env_files(),env_file_encoding="utf-8",extra="ignore",)diff --git a/pyproject.toml b/pyproject.tomlindex c8c6cbb5..4e4f93a3 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,3 +1,7 @@+[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"+[project]name = "free-claude-code"version = "2.0.0"@@ -19,6 +23,10 @@ dependencies = ["loguru>=0.7.0",]+[project.scripts]+free-claude-code = "cli.entrypoints:serve"+fcc-init = "cli.entrypoints:init"+[project.optional-dependencies]voice = ["grpcio>=1.78.0",@@ -32,6 +40,9 @@ voice_local = ["librosa>=0.10.0",]+[tool.hatch.build.targets.wheel]+packages = ["api", "cli", "config", "messaging", "providers"]+[tool.uv.sources]torch = { index = "pytorch-cu130" }