Skip to content

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.md
index 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 Works
diff --git a/cli/entrypoints.py b/cli/entrypoints.py
new file mode 100644
index 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.example
new file mode 100644
index 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 file
diff --git a/config/settings.py b/config/settings.py
index cdff8f80..16bd7697 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -1,6 +1,8 @@
"""Centralized configuration using Pydantic Settings."""
+import os
from functools import lru_cache
+from pathlib import Path
from pydantic import Field, field_validator, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -8,6 +10,17 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
from .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.toml
index 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" }