free-claude-code Documentation

File: README.md Copy Chapter

What You Get Copy Chapter

• 48 ToS-friendly providers. 1.3B+ free tokens every month. Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.
• 7 coding agents. One model catalog. Run Claude Code, Codex, Pi, OpenCode, Cline, Hermes, or DeepSeek Harness with your FCC models.
• Keep coding through provider outages. After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.
• Up to 90% fewer terminal-output tokens. Optional RTK filters common command output, while five FCC optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.
• Terminal, desktop, IDE, or phone. Work through native launchers, VS Code, Codex App, JetBrains, Discord, or Telegram.
• Voice notes in. Code out. Talk to your agent using local Whisper or NVIDIA NIM transcription.
• Agent capabilities stay intact. Stream responses, use tools, preserve native interleaved thinking for maximum performance, send images, and route Fable, Opus, Sonnet, and Haiku independently with compatible models.

Free-tier availability and limits are controlled by each provider and may change.

Quick Start Copy Chapter

1. Install Or Update Copy Section

macOS/Linux:

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh

Windows PowerShell:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1")))

Re-run the same command to update. When prompted, choose at least one coding agent and optionally RTK. You can review the installers before running them: install.sh and install.ps1.

2. Start FCC Copy Section

Windows

Open Free Claude Code from your desktop or Start menu.

macOS

Open Free Claude Code from your desktop or Applications folder.

Linux

Run:

fcc-server

FCC opens the Admin UI after starting. On Windows and macOS, use the tray or
menu-bar icon to open Admin, restart, or quit. When using fcc-server, keep its
terminal open.

3. Configure NVIDIA NIM Copy Section

1. Create an API key at build.nvidia.com/settings/api-keys.
2. Open the Admin UI URL from the server log.
3. Paste the key into NVIDIA_NIM_API_KEY.
4. Leave MODEL on the default nvidia_nim/nvidia/nemotron-3-super-120b-a12b, or search the model dropdown and select another model.
5. Click Validate, then Apply.

To protect the local proxy with a bearer token, enable Proxy Authentication
in Admin.

4. Run Your Coding Agent Copy Section

Claude Code:

fcc-claude

Codex:

fcc-codex

Pi:

fcc-pi

OpenCode:

fcc-opencode

Cline:

fcc-cline

Hermes:

fcc-hermes

DeepSeek Harness Web:

fcc-dsh

DeepSeek Harness headless:

fcc-dsh --profile headless "your task"

All seven launchers use the current Admin UI settings. Use the agent's model picker to choose from the models FCC exposes. Normal CLI arguments still work, for example:

fcc-codex exec "hello"

FCC launchers leave your existing agent settings, sessions, credentials, and
extensions unchanged. fcc-hermes starts attached sessions through FCC; choosing
another provider with Hermes /model intentionally leaves the FCC route.
fcc-dsh keeps DeepSeek Harness sessions and plugins while applying temporary
FCC provider settings. It currently supports the preview release 0.1.0-rc.8
on Node.js ^22.19 or >=24.

Choose A Provider Copy Chapter

1. Open a provider link below for its key, models, or setup instructions.
2. In the Admin UI, configure the listed setting. For OpenAI, use
   Providers → Connected accounts instead.
3. Search the MODEL dropdown and select a model. If the provider cannot list
   models, enter /<exact-provider-model-id> manually.
4. Click Validate, then Apply.

Optional: add an ordered Fallback Models list under Model Config. It
applies to every connected client. A failed request may reach and consume usage
from more than one provider before succeeding.

Provider catalog

Provider-specific setup

• OpenAI uses your ChatGPT subscription rather than an API key. Connect from
  Providers → Connected accounts in the Admin UI. Use device code on
  headless systems. Restart an already-running agent after connecting.
• Azure OpenAI uses the deployment names from your resource. Set
  AZURE_OPENAI_BASE_URL to its complete v1 endpoint, such as
  https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/, and select a
  deployment that supports Chat Completions. Enter the deployment name as a
  custom model slug if it does not appear in the model dropdown.
• Mistral Codestral uses a separate key from Mistral La Plateforme.
• Kimi Code subscription keys use kimi_code/; Kimi API credit keys use
  kimi/. Kimi Code plans are for personal interactive coding-agent use under
  Kimi's community guidelines.
• QwenCloud Coding Plan keys use qwencloud_coding/; QwenCloud Token Plan keys
  use qwencloud/. The keys and endpoints are not interchangeable. Coding Plan
  is for local, personal, interactive coding-agent use under the
  Coding Plan terms.
• OpenCode Zen and OpenCode Go share OPENCODE_API_KEY but use the explicit
  opencode_zen/ and opencode_go/ model prefixes.
• For Amazon Bedrock, set BEDROCK_BASE_URL to the URL for the same region as
  the API key and select one of the listed models.
• Vertex AI uses Google Application Default Credentials instead of an API key.
  Locally, run gcloud auth application-default login once; service-account
  files and attached service accounts also work. Set VERTEX_PROJECT_ID, and
  optionally change VERTEX_LOCATION from its global default.
• Cloudflare requires both its API token and account ID.
• For Ollama Cloud, use the exact model IDs shown in the model picker. Local
  Ollama uses the separate ollama/ prefix.
• Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.

Local provider setup

LM Studio Copy Section

Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the lmstudio/ prefix. The default URL is http://localhost:1234/v1.

llama.cpp Copy Section

Start llama-server with its OpenAI-compatible Chat Completions API and enough context for the model. Use the local model ID with the llamacpp/ prefix. LLAMACPP_BASE_URL defaults to http://localhost:8080/v1; FCC accepts either the server root or an explicit /v1 suffix.

Ollama Copy Section

ollama pull llama3.1
ollama serve

Use the tag shown by ollama list with the ollama/ prefix. OLLAMA_BASE_URL defaults to http://localhost:11434; FCC accepts either the root URL or an explicit /v1 suffix.

Optional model-tier routing

MODEL is the fallback for every request. Select a model for MODEL_FABLE, MODEL_OPUS, MODEL_SONNET, or MODEL_HAIKU to override an individual Claude Code tier; select None to use MODEL.

For example, route Opus to nvidia_nim/nvidia/nemotron-3-super-120b-a12b, Sonnet to open_router/openrouter/free, Haiku to lmstudio/qwen3.5-coder, and keep MODEL on zai/glm-5.2.

Reasoning control

Open Admin UI → Model Config → Reasoning and select the behavior you want.

Providers that do not support a selected control retain their own behavior.

Connect Your Client Copy Chapter

For terminal use, start fcc-server, then run fcc-claude, fcc-codex,
fcc-pi, fcc-opencode, fcc-cline, fcc-hermes, or fcc-dsh. Use the guides below for editor integrations.

Claude Code in VS Code

Install the Claude Code extension. Open VS Code's user settings as JSON and add:

"claudeCode.disableLoginPrompt": true,
"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" },
  { "name": "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "value": "190000" },
  { "name": "DISABLE_AUTOUPDATER", "value": "1" },
  { "name": "DISABLE_FEEDBACK_COMMAND", "value": "1" },
  { "name": "DISABLE_ERROR_REPORTING", "value": "1" }
]

Match the port and authentication token to the Admin UI, then reload the extension.

Codex App

Start FCC, then edit your Codex configuration:

• Windows: %USERPROFILE%\.codex\config.toml
• macOS: ~/.codex/config.toml

Add the matching model-catalog path and replace YOUR_USERNAME.

Windows:

model_catalog_json = "C:/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"

macOS:

model_catalog_json = "/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"

Then add the shared FCC settings:

model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"

[model_providers.fcc]
name = "Free Claude Code"
base_url = "http://127.0.0.1:8082/v1"
wire_api = "responses"

[model_providers.fcc.auth]
command = "fcc-codex"
args = ["--print-proxy-auth-token"]

Match the model and port to the Admin UI. The auth command reads FCC's current
proxy token automatically. Restart the Codex App after setup or model changes,
then select an FCC model from its model picker.

Codex in VS Code

Install the Codex extension. Create or edit ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"

[model_providers.fcc]
name = "Free Claude Code"
base_url = "http://127.0.0.1:8082/v1"
wire_api = "responses"

[model_providers.fcc.auth]
command = "fcc-codex"
args = ["--print-proxy-auth-token"]

Match model and the port to the Admin UI. The auth command reads FCC's current
proxy token automatically. Restart VS Code after setup or model changes. For
WSL-backed Codex, edit the file inside WSL.

Claude Code in JetBrains ACP

Edit the installed Claude ACP configuration:

• Windows: C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
• Linux/macOS: ~/.jetbrains/acp.json

Set the environment for acp.registry.claude-acp:

"env": {
  "ANTHROPIC_BASE_URL": "http://localhost:8082",
  "ANTHROPIC_AUTH_TOKEN": "freecc",
  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  "DISABLE_AUTOUPDATER": "1",
  "DISABLE_FEEDBACK_COMMAND": "1",
  "DISABLE_ERROR_REPORTING": "1"
}

Match the port and token to the Admin UI, then restart the IDE.

Claude Code still asks you to log in

If Claude Code asks you to log in after you configure the FCC URL and token, open its state file:

• Windows: %USERPROFILE%\.claude.json
• macOS/Linux/WSL: ~/.claude.json

Merge this property into the existing JSON without removing its other fields:

"hasCompletedOnboarding": true

If the file does not exist, create it with a complete JSON object:

{
  "hasCompletedOnboarding": true
}

Restart Claude Code or the IDE after saving the file.

Optional Integrations Copy Chapter

Configure integrations from Admin UI → Messaging, then click Validate and Apply.

Discord bot

1. Create a bot in the Discord Developer Portal.
2. Enable Message Content Intent and invite it with read, send,
   message-history, and Manage Messages permissions so /clear can remove
   user prompts.
3. Set Messaging Platform to discord.
4. Enter Discord Bot Token, Allowed Discord Channels, and an absolute Allowed Directory.
5. Apply the settings and restart the server if requested.

Telegram bot

1. Create a bot with @BotFather.
2. Get your numeric user ID from @userinfobot.
   In groups, grant the bot permission to delete messages.
3. Set Messaging Platform to telegram.
4. Enter Telegram Bot Token, Allowed Telegram User ID, and an absolute Allowed Directory.
5. Apply the settings and restart the server if requested.

Messaging commands Copy Section

Voice notes

Choose the voice backend you want, then re-run the installer with its option.

The examples below install NVIDIA NIM transcription. To use another backend,
replace the final option with the matching one from the table.

macOS/Linux:

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-nim

Windows PowerShell:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceNim

Restart fcc-server. In Admin UI → Messaging → Voice, enable voice notes, select cpu, cuda, or nvidia_nim, and choose the Whisper model. Local gated models need HUGGINGFACE_API_KEY; NVIDIA NIM transcription needs NVIDIA_NIM_API_KEY.

Manage Your Installation Copy Chapter

Run fcc-server --version to check the installed version without starting FCC.

Update Copy Section

Re-run the matching command from Install Or Update.

Uninstall Copy Section

Stop every running FCC command before uninstalling.

Removes

• Free Claude Code, including its desktop launcher and commands
• ~/.fcc/

Keeps

• uv and Python
• Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, and RTK
• Shared PATH entries

macOS/Linux:

curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh

Windows PowerShell:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/uninstall.ps1")))

Project Links Copy Chapter

• Report bugs or request features
• Architecture and extension guide
• Contributing guide

License Copy Chapter

MIT License. See LICENSE for details.

File: smoke/README.md Copy Chapter

Product E2E Smoke Tests

smoke/ is local-only. It can launch subprocesses, call real providers, touch
local model servers, and optionally send/delete bot messages. Hermetic contracts
belong under tests/ and must stay green with plain uv run pytest.

Taxonomy Copy Chapter

• smoke/prereq/: liveness checks that prove the server, routes, auth, CLI
  scripts, provider pings, local /models, and bot permissions are reachable.
  These are prerequisites only.
• smoke/product/: end-to-end product scenarios. Feature smoke coverage comes
  from these tests, not from route/header/provider pings.
• smoke/features.py: source-of-truth feature map:
  feature -> subfeature -> scenario -> env -> expected behavior -> failure class.

Required Local Commands Copy Chapter

uv run pytest smoke --collect-only -q
uv run pytest smoke -n 0 -s --tb=short

The second command skips everything unless FCC_LIVE_SMOKE=1 is set, but still
writes skip entries to .smoke-results/.

Product Smoke Run Copy Chapter

$env:FCC_LIVE_SMOKE = "1"
uv run pytest smoke -n 0 -s --tb=short

Provider smoke scenarios can run providers in parallel while preserving
sequential execution within each provider:

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "providers"
uv run pytest smoke -n auto --dist=loadgroup -s --tb=short

Provider product E2E runs once per configured provider, independent of MODEL,
MODEL_FABLE, MODEL_OPUS, MODEL_SONNET, and MODEL_HAIKU. Defaults come from the provider
catalog/docs and can be overridden with FCC_SMOKE_MODEL_, for example
FCC_SMOKE_MODEL_DEEPSEEK=deepseek-v4-pro (or deepseek-v4-flash). If no provider smoke model is
configured, live product smoke fails as missing_env unless you explicitly set
FCC_ALLOW_NO_PROVIDER_SMOKE=1.

Targets Copy Chapter

Default targets do not send real bot messages or load voice backends:

Heavy/side-effectful targets are opt-in:

Examples Copy Chapter

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_PROVIDER_MATRIX = "open_router,nvidia_nim,deepseek,lmstudio,llamacpp,ollama"
uv run pytest smoke/product -n 0 -s --tb=short

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "ollama"
$env:OLLAMA_BASE_URL = "http://localhost:11434"
uv run pytest smoke/prereq smoke/product -n 0 -s --tb=short

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "telegram,discord,voice"
$env:FCC_SMOKE_RUN_VOICE = "1"
uv run pytest smoke/product -n 0 -s --tb=short

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "nvidia_nim_cli"
$env:FCC_SMOKE_NIM_MODELS = "z-ai/glm-5.2,moonshotai/kimi-k2.6,minimaxai/minimax-m2.7,minimaxai/minimax-m3,nvidia/nemotron-3-super-120b-a12b,deepseek-ai/deepseek-v4-pro,deepseek-ai/deepseek-v4-flash"
uv run pytest smoke/product -n 0 -s --tb=short

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "openrouter_free_cli"
$env:FCC_SMOKE_OPENROUTER_FREE_MODELS = "nvidia/nemotron-3-super-120b-a12b:free,openai/gpt-oss-120b:free,poolside/laguna-m.1:free"
uv run pytest smoke/product -n 0 -s --tb=short

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "cli"
$env:FCC_SMOKE_PROVIDER_MATRIX = "openai"
$env:FCC_SMOKE_MODEL_OPENAI = "gpt-5.6-luna"
uv run pytest smoke/product/test_client_product_live.py -n 0 -s --tb=short -k claude_auto_mode_openai_connected

$env:FCC_LIVE_SMOKE = "1"
$env:FCC_SMOKE_TARGETS = "messaging,config,extensibility"
uv run pytest smoke/product -n 0 -s --tb=short

Environment Copy Chapter

• Runtime settings use the isolated managed ~/.fcc/.env; FCC_ENV_FILE is
  exercised only by the one-time legacy migration smoke.
• FCC_LIVE_SMOKE=1: enables live smoke execution.
• FCC_ALLOW_NO_PROVIDER_SMOKE=1: permits no-provider live smoke for harness work.
• FCC_SMOKE_TARGETS: comma-separated targets, or all.
• FCC_SMOKE_PROVIDER_MATRIX: comma-separated provider prefixes to require.
• FCC_SMOKE_MODEL_: optional per-provider smoke model override.
  Use the uppercase provider ID, such as FCC_SMOKE_MODEL_KILO; the complete
  variable inventory is in .env.example. Values may include
  the provider prefix or just the model name for that provider.
• FCC_SMOKE_MODEL_MISTRAL_REASONING: optional override for the dedicated
  Mistral native reasoning smoke, default mistral/mistral-medium-3-5.
• FCC_SMOKE_NIM_MODELS: optional comma-separated NVIDIA NIM CLI matrix models
  that replace the default characterization set.
• FCC_SMOKE_NIM_EXTRA_MODELS: optional comma-separated NVIDIA NIM CLI matrix
  models appended to the default or replacement set.
• FCC_SMOKE_OPENROUTER_FREE_MODELS: optional comma-separated OpenRouter free
  CLI matrix models that replace the default characterization set.
• FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS: optional comma-separated OpenRouter
  free CLI matrix models appended to the default or replacement set.
• FCC_SMOKE_TIMEOUT_S: per-request/subprocess timeout, default 45.
• FCC_SMOKE_CLAUDE_BIN: Claude CLI executable name, default claude.
• FCC_SMOKE_RUN_WEB_TOOLS=1: enables the combined real-provider automatic
  WebSearch and installed Claude Code WebSearch scenario, including a public
  DuckDuckGo request.
• FCC_SMOKE_TELEGRAM_CHAT_ID: Telegram chat/user ID for send/edit/delete.
• FCC_SMOKE_DISCORD_CHANNEL_ID: Discord channel ID for send/edit/delete.
• FCC_SMOKE_INTERACTIVE=1: enables manual inbound Telegram/Discord checks.
• FCC_SMOKE_RUN_VOICE=1: allows voice transcription backends to load/run.

Windows / nested `uv run` Copy Chapter

Run smoke the same way you run tests (uv run pytest smoke from the repo). Child
processes use the same Python interpreter as the test runner, not nested
uv run, so Windows does not try to replace fcc-server.exe while it is
locked.

Failure Classes Copy Chapter

Smoke artifacts are written to .smoke-results/ and redact env values whose
names contain KEY, TOKEN, SECRET, WEBHOOK, or AUTH.

• missing_env: required credentials, binary, provider config, local provider
  server/model, or opt-in flag is absent.
• upstream_unavailable: a real provider or bot API is not reachable.
• probe_timeout: the smoke driver reached the target, but the CLI/probe did
  not complete within the smoke timeout.
• product_failure: the app accepted the scenario but returned the wrong shape,
  crashed, leaked state, or violated the product contract.
• harness_bug: the smoke test or driver made an invalid assumption.
• target_disabled: skipped because FCC_SMOKE_TARGETS intentionally selected
  a different target.

product_failure and harness_bug are failures. missing_env,
upstream_unavailable, and probe_timeout are skips except when the user
explicitly selected a provider in FCC_SMOKE_PROVIDER_MATRIX;
selected-but-missing providers fail.