Free Claude Code: a local gateway for coding agents and your own providers

Everything worth knowing about Alishahryar1/free-claude-code: a local proxy that connects Claude Code, Codex and Pi to cloud or local models chosen by whoever installs it.

---

What Free Claude Code is

Free Claude Code (FCC) is a local proxy, distributed under the MIT license, for using coding-agent clients without changing their usual interface. According to its README and architecture document, it receives Anthropic Messages traffic from Claude Code and Pi, and OpenAI Responses traffic from Codex; it converts and routes it to the configured provider.

It does not provide a model itself, nor does it guarantee that a provider is free: the name reflects that it lets you pick providers with free, paid, or local plans. The decision about cost, credentials, and model remains the user’s. The README states 31 configurable providers from a local admin interface and support for streaming, tools, reasoning, and images when the chosen provider supports them.

The origin: from an NVIDIA NIM experiment to a multi-provider gateway

The current repository was created on January 28, 2026 by Alishahryar1, whose account identifies as Ali Khokhar and describes their activity as writing understandable code. No external publication documenting the exact launch of the current repository was retrieved.

An announcement from the same author on Hacker News was retrieved, dated February 6, 2026: thread 46917761, linked to another of their repositories, Alishahryar1/claude-code-free. Khokhar recounted that they started an implementation with Claude Code and, after getting it working, used it to develop the project itself. There they described a middleware between Claude Code and NVIDIA NIM, Telegram for remote tasks, preservation of reasoning across tool calls, rate limiting, and concurrency. The submission got 3 points and 0 comments, so it substantiates the author’s account, not independent reception or the exact technical identity between that repository and the current one.

The tension it tries to resolve is practical: keep the clients and extensions of Claude Code, Codex, or Pi while replacing the upstream provider with your own credential, a compatible service, or a local server.

Philosophy and principles

• Local control of the model path: the admin interface runs locally and lets you validate a provider before applying it.
• Not tied to a single client: the fcc-claude, fcc-codex, and fcc-pi launchers point their clients at the same gateway.
• Preserve protocol contracts: the architecture distinguishes Anthropic Messages from OpenAI Responses so the client keeps using its expected protocol.

• Configure by capability, not by brand: the README documents model selection, per-tier Claude routing, reasoning controls, and separate local providers.
• Separation between application and provider: the architecture document places routing, executors, and provider adapters at distinct boundaries, with an HTTP interface, launchers, and, optionally, a messaging bridge.

How it works

The fcc-server server exposes a FastAPI API with compatible routes, health, model listing, stop, and admin. Claude Code, Codex, and Pi clients are configured against http://127.0.0.1:8082 via the launchers; the local interface lets you save the provider, choose a model identifier, and validate the configuration.

The retrieved architecture describes three surfaces: the HTTP proxy, the command-line launchers, and an optional Discord or Telegram bridge. The latter starts managed client sessions and offers messaging commands like /stats, /stop, and /clear.

The README lists cloud providers — among others NVIDIA NIM, OpenAI, OpenRouter, Google AI Studio, DeepSeek, Mistral, OpenCode, Vercel AI Gateway, Bedrock, Hugging Face, Groq, and Cloudflare — and three local routes: LM Studio, llama.cpp, and Ollama. The list reflects integrations FCC declares; it does not imply endorsement from all those companies.

Official and semi-official status

No evidence was found that FCC has been accepted into an official marketplace run by Anthropic, OpenAI, Pi, VS Code, or JetBrains, nor of any certification or sponsorship from those providers. Its status is therefore community-driven and independent.

In practice it integrates official clients and extensions through local configuration: the README documents the Claude Code extension for VS Code, the Codex extension for VS Code, and Claude ACP for JetBrains. That means compatibility configured by the project, not approval from each client’s provider.

The ecosystem

The author’s repositories

The GitHub API returned seven public repositories from Alishahryar1. Besides FCC, there are forks or projects named llama.cpp, opencode, and vllm, along with the repositories avazu-ctr, gpu-ops-platform, and Machine-Learning-Methods-in-Physics. No documentation was retrieved establishing that these are components, dependencies, or sibling products of FCC; they should therefore not be read as its official ecosystem.

Verified forks, ports, and extensions

• sepehrbayat/SEPCC (36 stars) explicitly presents itself as a fork of Free Claude Code that adds context persistence across restarts and routing for more than 17 providers.
• simplesunny/free-claude-code (28 stars) is a visible fork with a description of usage from terminal, VS Code, or Discord.
• rishiskhare/free-claude-code (20 stars) is a fork oriented toward NVIDIA NIM, terminal, and Telegram; diyism/cc-nim (19 stars) publishes the same NIM/Telegram orientation.
• The GitHub search also returned Abdl-Dev/-Free-Claude-Code-Ultimate-Beginner-Setup-Troubleshooting-Guide (3 stars), an installation and troubleshooting guide for FCC. It is community material, not official documentation.

The query over the 30 most-starred forks did not return a non-English translation clearly documented as such. Therefore, no official or specific community translation is claimed to exist. The figures in this section reflect the GitHub search/API measurement from August 6, 2026.

Related projects and category comparison

• router-for-me/CLIProxyAPI (46,294 stars) is described as a service compatible with the OpenAI, Gemini, Claude, and Codex APIs that wraps several clients. It overlaps with FCC in the role of multi-protocol proxy; the implementations differ (Go versus Python as FCC’s main language according to GitHub).
• diegosouzapw/OmniRoute (40,935 stars) presents itself as an MIT gateway with more than 290 providers and code clients. It overlaps in model routing; the search description attributes fallback routes and other integrations to OmniRoute that should not automatically be carried over to FCC.
• decolua/9router (24,763 stars) advertises connecting multiple agents to more than 40 providers with fallback routes. This is a comparison of gateways, not proof of functional equivalence.
• siteboon/claudecodeui (13,122 stars) presents itself as a web/graphical interface for remote Claude Code, OpenCode, Cursor CLI, and Codex sessions. It is complementary: FCC routes requests; this project focuses on managing sessions and projects remotely.

Repo numbers

Measured: August 6, 2026, GitHub API.

Metric	Value
Stars	44,535
Forks	7,347
Real subscribers	301
Commits	873
Open issues reported by the API	345
Main language	Python
License	MIT
Created	January 28, 2026
Metadata last updated by GitHub	August 6, 2026
Latest release retrieved	No GitHub releases retrieved

The total of 873 commits comes from the last page indicated by the commits API’s pagination link. The top contributors returned by the API were Alishahryar1 (740 contributions), cursoragent (53), dependabot[bot] (24), rishiskhare (7), and claude (6). open_issues_count may include open pull requests; it does not necessarily equal issues exclusively. The API repeats the star count in watchers_count, so subscribers_count is reported as real subscribers.

The metadata and activity update date from the API coincides with the date of this measurement; it is not interpreted as a future projection.

How to contribute

The repository has a contributing guide. It asks contributors to open an issue before proposing README changes, not to submit pull requests integrating Docker, and, for bugs, to attach model mappings, the active model, the full error, and reproduction steps.

For development it requires uv and Python 3.14, and documents this bootstrap:

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
uv python install 3.14.0
uv run fcc-server

Before a pull request, ./scripts/ci.sh runs on macOS/Linux or ./scripts/ci.ps1 on Windows. The process includes formatting and checking with Ruff, type checking with ty, and testing with Pytest. Changes to code, dependencies, packaging, or installation require bumping the semantic version in pyproject.toml and uv.lock within the same change.

How the community received it

The external evidence retrieved is limited, but there are concrete signals of usefulness and objections:

• In HN 48004559, about using cheaper models with Claude, ashish0112 wrote that FCC can delegate model calls while keeping Claude’s orchestration. Algolia’s search placed it as a comment within a thread whose score and total comment count were not retrieved in the history query; the comment text is verified via the root element, but figures for the thread are not invented.
• The author’s own announcement, HN 46917761, got 3 points and 0 comments. It serves as a primary source for intent and early capabilities, not as independent review.
• In discussion 222, ruslaniv questioned the use case versus OpenCode and asked what advantage FCC brought. The question had 3 comments: it is a concrete critique of differentiation, not a demonstrated technical conclusion.
• Issue #342 records that debarpon2610 experienced provider errors after 15–20 minutes in more than 75% of their cases; it had 32 comments when retrieved. In #319, neno-research reported NVIDIA timeouts and that manually resuming allowed them to continue; it had accumulated 23 comments. These are user experiences, not a measure of general reliability.

Searches were attempted on Reddit, X, Product Hunt, blogs, and newsletters via direct web search; the search service returned responses with no retrievable results. No Product Hunt page, verifiable X launch, Dev.to/Hashnode review, or attributable podcast/newsletter was found for the repository. No independent official page was retrieved either: GitHub and the repository’s documents are the official documentation available in this investigation.

Quick usage guide

Installation and first run

The README requires using the project’s installer. On macOS or Linux:

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

On Windows, the documented PowerShell installer is used:

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

The installer asks which agents will be installed or verified; at least one must be chosen. On Linux, fcc-server is started; on Windows and macOS the app appears in the tray/menu bar. Once the server is healthy, it opens or displays the local admin interface, usually at http://127.0.0.1:8082/admin.

Common workflows

1. Claude Code with a configured provider: start fcc-server, validate and apply the provider in the interface, and run fcc-claude. The native /model selector shows the models FCC exposes.
2. Codex from the terminal: with the server running, run fcc-codex; for a non-interactive task, the README gives fcc-codex exec "hello" as an example.
3. Pi without altering its permanent configuration: run fcc-pi. The README states it registers FCC only for that process and preserves Pi’s existing sessions, credentials, and extensions.
4. Local provider with Ollama: run ollama pull llama3.1 and ollama serve; then select an identifier prefixed with ollama/ in FCC. The default URL is http://localhost:11434.

Essential configuration

• Admin interface → provider and MODEL: credential, validation, and default model. If the provider does not list models, the README allows writing <provider-id>/<exact-model-id>.
• MODEL_FABLE, MODEL_OPUS, MODEL_SONNET, MODEL_HAIKU: selectively override MODEL for Claude Code tiers; the value None keeps the default model.
• Admin → Model configuration → reasoning: keeps the client’s setting, disables it, or forces a level; providers without that capability keep their existing behavior.
• ~/.fcc/auth/: location of renewable credentials that FCC stores when connecting an OpenAI/ChatGPT subscription; it does not modify Codex’s own login.
• ~/.codex/config.toml: file the README configures for Codex App or VS Code when not using the launcher, with base_url = "http://127.0.0.1:8082/v1" and a Bearer header equivalent to the local token.

Common pitfalls and fixes

• Claude Code keeps asking to sign in: add "hasCompletedOnboarding": true to ~/.claude.json on macOS/Linux/WSL, or to %USERPROFILE%\.claude.json on Windows, and restart the client; this is the documented fix.
• Model or provider fails after starting fine: do not assume it is a universal FCC failure. Issues #342, #319, #416, and #449 describe provider errors and timeouts, especially with NVIDIA NIM or OpenRouter. Confirm the model, the credential, and the full message, and provide that data in an issue, as the contributing guide requires.
• Azure doesn’t show the deployment: Azure does not publish custom deployment names in its model list; the README says to enter the name as a manual slug and use the full v1 endpoint in AZURE_OPENAI_BASE_URL.
• Switching models while the agent is already open: restart the agent after connecting OpenAI or changing models to refresh the selector.
• Don’t leave fcc-server in the foreground on Linux: the README warns that the terminal must stay open when running it with that command.

Integrations and migration

FCC documents configuration for Claude Code in VS Code, Codex App, Codex in VS Code, and Claude ACP in JetBrains. For VS Code/Claude, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY are used; for Codex, an fcc provider is configured in ~/.codex/config.toml.

It also integrates Discord and Telegram from Admin → Messaging. Bot token, allowed channel or user, and allowed directory are configured; voice notes can use NVIDIA NIM or local Whisper. No formal migration guide from another gateway was retrieved. The documented migration consists of keeping Claude Code, Codex, or Pi and changing their variables or configuration to point to the local proxy.

Use cases and who this repository can help

• Anyone already working with Claude Code, Codex, or Pi who wants to keep their terminal or IDE workflow can redirect those clients to compatible models without adopting a different agent interface.
• Teams or individuals with several provider credentials can validate a provider in a local interface, select a default model, and, for Claude Code, assign different models to Fable, Opus, Sonnet, and Haiku.
• Developers running local models can connect LM Studio, llama.cpp, or Ollama, as long as the server exposes a compatible API and the model supports the context and tools the agent needs.
• Users operating from mobile or messaging apps can use the Discord or Telegram bridge, with controls for directory, allowed users/channels, cancellation, and session cleanup. They should treat bot tokens, allowed directories, and provider credentials as sensitive configuration.
• Maintainers who want to extend a protocol gateway will find in ARCHITECTURE.md an explicit split between proxy, launchers, messaging bridge, and provider adapters, along with a CI sequence and versioning rules.

Resources

• Repository: https://github.com/Alishahryar1/free-claude-code
• Documentation and installation: https://github.com/Alishahryar1/free-claude-code#quick-start
• Architecture and extensions: https://github.com/Alishahryar1/free-claude-code/blob/main/ARCHITECTURE.md
• How to contribute: https://github.com/Alishahryar1/free-claude-code/blob/main/CONTRIBUTING.md
• Discussions and reception: https://news.ycombinator.com/item?id=46917761, https://news.ycombinator.com/item?id=48004559, https://github.com/Alishahryar1/free-claude-code/discussions/222
• Provider issues: https://github.com/Alishahryar1/free-claude-code/issues/342, https://github.com/Alishahryar1/free-claude-code/issues/319
• Video found in the search: https://www.youtube.com/watch?v=d5pr0tB6h0o — a video by Alex Hitt whose visible title describes the GitHub proxy to NVIDIA NIM; view count was not retrieved.
• Same-name npm registry entry, not attributed to the current repository: https://www.npmjs.com/package/free-claude-code — 207 downloads between July 29 and August 4, 2026, but its metadata points to shurukon/FCC; it is not a metric for Alishahryar1’s FCC.

---

Note: this article combines the README, architecture, and contributing guide of Free Claude Code, the GitHub API, GitHub Discussions/issues, Hacker News, package registries, and a YouTube search, all consulted on August 6, 2026. Figures change over time.