Free Claude Code Explained: One Local Proxy for 50+ AI Providers

You want Claude Code, Codex, or Pi — but you do not want a second subscription, a sketchy reverse proxy, or a setup that breaks the moment one provider rate-limits you.

Then free-claude-code shows up with 50k+ GitHub stars and a promise: 1.3B+ free tokens, nine coding agents, ToS friendly. Sounds too good. What is the catch?

The catch is simpler than you think: FCC is not a magic free API. It is a local proxy + admin layer that sits between your coding agents and the providers you already have access to — free tiers, subscriptions, API keys, or local models. One install, one config UI, many agents.

Repository: Alishahryar1/free-claude-code

---

TL;DR

• What it does: Runs fcc-server on your machine; agents talk to localhost:8082 instead of Anthropic/OpenAI directly.
• Pain without it: Separate API keys per agent, manual model switching when a provider fails, and gray-area proxies that risk account bans.
• What changes: One Admin UI configures 50+ providers, ordered fallbacks, tier routing (Opus/Sonnet/Haiku), and launchers like fcc-claude / fcc-codex.
• Who should use it: Developers juggling free tiers or multiple providers who want Claude Code’s UX without vendor lock-in.
• Who should skip it: Teams with a single paid Anthropic contract and no appetite for local Python infra.

Before FCC, every coding agent is its own island: its own env vars, its own API key drawer, its own outage story.

FCC collapses that into one control point: agents hit the local proxy; the proxy picks the model, retries, and falls through your ordered provider list.

Keep the pair in mind: without FCC, you are the integration layer. With FCC, the proxy is.

---

Beginner Map

Read this post against the two scenes above:

1. Pass 1: See why per-agent API keys become operational debt.
2. Pass 2: Memorize fcc-server → Admin UI → fcc-claude (or fcc-codex).
3. Pass 3: Learn the vocabulary: MODEL, fallback list, tier overrides, RTK.
4. Pass 4: Run the first exercise below on your machine.

Term	Question it answers
fcc-server	What process listens on localhost:8082?
Admin UI	Where do I paste API keys and pick models?
MODEL	Which provider/model handles a request by default?
Fallback Models	What runs when the primary provider fails?
fcc-claude	How does Claude Code reach FCC instead of Anthropic?
RTK	How does FCC shrink noisy terminal output before it hits the model?

First Practical Exercise

Install FCC, start the server, paste one free provider key (NVIDIA NIM is the README default), validate, apply, then run:

fcc-claude

Inside Claude Code, open /model and confirm FCC models appear. If they do, the “with” scene is real — everything else is configuration detail.

Stretch goal: Add a second provider to Fallback Models, then temporarily break the primary key. Watch the same agent turn continue on the backup without a manual restart.

---

Part 1: Foundations — the mental model

Think of coding agents as appliances and model providers as power companies. Claude Code expects Anthropic-shaped electricity. Codex expects OpenAI-shaped electricity. Groq, Gemini, and local Ollama each speak slightly different dialects.

Without an adapter, you buy a separate wall plug for every appliance. With FCC, you install one power strip with a smart router: the appliance plugs into localhost:8082; FCC translates the request, bills the right provider, and switches circuits when one trips.

That is the central control point in the “with” scene: fcc-server is not the model — it is the router.

Important nuance the star count hides: FCC does not generate tokens for free out of thin air. It aggregates legitimate free tiers and keys you supply. The “1.3B+ free tokens” headline is the sum of documented monthly allowances across cataloged providers — each with its own limits, terms, and availability. FCC’s value is orchestration, not alchemy.

The project is also explicit: independent open-source, not affiliated with Anthropic. Claude and Claude Code are Anthropic trademarks. FCC routes to compatible endpoints; it does not replace Anthropic’s product or support.

---

Part 2: The Investigation — what actually happens?

Here is the happy path from zero to coding, mapped to the scene arrows.

Step 1: Install or update

Review the installer before you pipe it. Then pick your OS.

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 — a filter that strips repetitive terminal noise so fewer tokens reach the model.

Nine launchers after install:

Command	Agent
fcc-claude	Claude Code
fcc-codex	Codex
fcc-pi	Pi
fcc-opencode	OpenCode
fcc-cline	Cline
fcc-hermes	Hermes
fcc-dsh	DeepSeek Harness
fcc-grok	Grok Build
fcc-muse	Muse Code

Step 2: Start fcc-server

• macOS/Windows: Launch Free Claude Code from Applications or Start menu.
• Linux: Run fcc-server and keep the terminal open.

The server prints an Admin UI URL. Tray/menu-bar icons on desktop OSes expose restart and quit.

Step 3: Configure a provider in Admin UI

Example with NVIDIA NIM (README default):

1. Create a key at build.nvidia.com/settings/api-keys.
2. Open Admin UI → paste NVIDIA_NIM_API_KEY.
3. Leave MODEL on nvidia_nim/nvidia/nemotron-3-super-120b-a12b or search the dropdown.
4. Validate → Apply.

Optional: enable Proxy Authentication so only clients with the bearer token can hit the proxy.

ChatGPT is not an API key. Open Providers → Connected accounts, sign in with the official ChatGPT flow (device code on headless boxes), then restart any already-running agent. OpenAI-shaped clients then use openai/<model-id>.

Step 4: Launch an agent through FCC

fcc-claude    # Claude Code
fcc-codex     # Codex
fcc-pi        # Pi
fcc-opencode  # OpenCode
fcc-cline     # Cline
fcc-hermes    # Hermes
fcc-dsh       # DeepSeek Harness
fcc-grok      # Grok Build
fcc-muse      # Muse Code

Each launcher sets the env vars that agent expects (ANTHROPIC_BASE_URL, OpenAI-compatible base URL, etc.) to point at FCC instead of the vendor cloud.

Step 5: IDE integration (optional)

For Claude Code in VS Code, point ANTHROPIC_BASE_URL at http://localhost:8082 and set ANTHROPIC_AUTH_TOKEN to match Admin UI. Enable CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 so /model lists FCC catalog entries.

For Codex App, add an fcc model provider in ~/.codex/config.toml with base_url = "http://127.0.0.1:8082/v1" and auth via fcc-codex --print-proxy-auth-token.

What happens on each request?

1. Agent sends an Anthropic- or OpenAI-shaped request to FCC.
2. FCC resolves MODEL (or tier override — see Part 3).
3. FCC calls the provider adapter (NVIDIA NIM, OpenRouter, Groq, local Ollama, …).
4. On failure after retries, FCC walks Fallback Models in order — same turn, no agent restart.
5. Optional RTK and five built-in optimizations trim command output and metadata before the next provider call.

The README claims up to 90% fewer terminal-output tokens when RTK is enabled — meaningful when agents dump build logs into context.

---

Part 3: The Diagnosis — terms that cause confusion

provider-id/model-id slugs

Models in Admin UI use a two-part slug: open_router/openrouter/free, groq/llama-3.3-70b-versatile, ollama/llama3.1. The prefix selects the adapter; the suffix is the provider’s exact model identifier. If a provider cannot list models, type the slug manually.

Tier routing (Fable, Opus, Sonnet, Haiku)

Claude Code internally labels tiers. FCC lets you map each tier to a different backend:

• MODEL — default for everything.
• MODEL_OPUS, MODEL_SONNET, MODEL_HAIKU, MODEL_FABLE — overrides per tier; None inherits MODEL.

Example strategy: Opus-tier tasks on a large free NIM model, Haiku-tier on a fast local lmstudio/ tag, default MODEL on OpenRouter free.

Reasoning control

Admin UI → Model Config → Reasoning can force effort off/low/high or pass through what the client sends. Providers that ignore reasoning flags keep their native behavior — FCC does not fabricate chain-of-thought.

Messaging integrations (Discord / Telegram)

FCC is not only terminal-first. Configure Admin UI → Messaging to run agents from chat, with /stats, /stop, and /clear commands. Voice notes optional via local Whisper or NVIDIA NIM transcription — closer to OpenClaw’s omnichannel pitch, but scoped to coding-agent sessions in an allowed directory.

“ToS friendly” — what that actually means

FCC markets compliance: use official APIs and subscription flows (e.g. ChatGPT connect in Admin UI), remove integrations when providers disallow them. That is not a guarantee your account is safe — provider terms change. Treat free tiers as best-effort, read each provider’s limits, and avoid sharing one key across abusive automation.

FCC vs. unofficial Claude proxies

Approach	Risk profile	What you get
Random “free Claude API” relay	High — often violates ToS, keys leaked	Fragile, account ban roulette
Direct Anthropic API	Low — official	Full fidelity, pay per token
FCC	Medium — depends on providers you configure	Multi-agent, multi-provider, local control

---

Part 4: The Resolution — tradeoffs and when to use it

When FCC shines

• You already bounce between free tiers (NIM, OpenRouter free, Groq, Gemini flash) and want one config surface.
• You run multiple agents (Claude Code + Codex + Pi) and refuse to duplicate keys in three env files.
• Provider outages are common in your region — ordered fallback saves a half-finished refactor.
• You want local or hybrid models (Ollama, LM Studio, llama.cpp) in the same picker as cloud models.
• You experiment from phone or chat via Discord/Telegram without building OpenClaw-scale automation.

When to skip or defer

• Your team standardizes on one Anthropic enterprise contract — adding a Python proxy is pure ops overhead.
• You need vendor SLAs, audit trails, and support tickets — FCC is MIT hobby infra, not a managed gateway.
• You cannot run a persistent local service (locked-down corp laptop, ephemeral CI only).
• You expect frontier-model fidelity every session — free routes may lag newest Opus capabilities.

Compared to OpenClaw

OpenClaw is a proactive personal operator across messaging, cron, and OS nodes. FCC is a model router for coding agents. They solve different layers: OpenClaw decides when to act; FCC decides which model answers when Claude Code already has a prompt. You could run both — OpenClaw triggering tasks, FCC backing the coding session — but neither replaces the other.

Minimal production-minded setup

1. Run fcc-server on a machine that stays awake (home server or dev box).
2. Enable Proxy Authentication if the port is reachable on your LAN.
3. Configure two providers minimum — primary + fallback.
4. Pin versions: re-run the install script to update; check fcc-server --version before upgrades.
5. Keep Claude Code onboarding happy: set "hasCompletedOnboarding": true in ~/.claude.json if login prompts persist after FCC config.

---

Final Take

Free Claude Code is a universal adapter for coding agents — not a free lunch, but a local control plane that makes free tiers, subscriptions, and local models look like one catalog to Claude Code, Codex, and friends.

One sentence to remember: point every agent at localhost:8082, let FCC own the provider chaos.

Do this today: install FCC, configure one free provider, run fcc-claude, and add a fallback model before your next long refactoring session.