my-free-code README

The project's README from github.com/hkqr/my-free-code. As one markdown file: README.md.

My Free Code v0.8

A multi-provider gateway for Claude Code and other coding agents.

It is an independent implementation. It is not affiliated with Anthropic.

What v0.8 includes

Gateway protocols

Agent features

Provider layer

The catalog contains the broad provider set used by the project:

NVIDIA NIM, OpenRouter, Groq, OpenAI, xAI, QwenCloud, Together, DeepInfra, SiliconFlow, Nebius, Chutes, Featherless, ZenMux, W&B Inference, Azure OpenAI, Google AI Studio, Google Vertex, DeepSeek, Mistral, Codestral, OpenCode Zen, OpenCode Go, Vercel AI Gateway, Amazon Bedrock, Hugging Face, Cohere, GitHub Models, Wafer, Kimi, Kimi Code, MiniMax, Cerebras, SambaNova, Kilo, Fireworks, Novita, Cloudflare Workers AI, Z.ai, TokenRouter, NaraRoute, Poolside, LLM7, Ollama Cloud, LM Studio, llama.cpp and Ollama.

Provider entries are not fake claims of universal support: providers with unusual authentication/protocols require a dedicated adapter. The common OpenAI-compatible providers use the shared transport.

Coding-agent launcher layer

The architecture has launcher adapters for:

A launcher simply prepares the local proxy environment and delegates arguments to the installed client.

Architecture

             Coding Agents / IDEs
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI Gateway
                      |
                Model Router
                      |
          +-----------+-----------+
          |                       |
       Primary                  Fallbacks
          |                       |
          +-----------+-----------+
                      |
              Provider Runtime
                      |
       +--------------+--------------+
       |              |              |
 OpenAI-compatible  Specialized   Local
     adapter          adapter     runtime
       |              |              |
     APIs          provider API  Ollama/LM Studio

The architecture deliberately separates wire protocols from routing and provider code. This mirrors the important architectural boundary in the current reference project: HTTP adapters, application routing/execution, provider runtime, CLI adapters and optional messaging are separate concerns. citeturn0search0

Install

Python 3.10+.

python -m venv .venv

Windows:

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

macOS/Linux:

source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

Start:

python -m my_free_code

Default address:

http://127.0.0.1:8082

Configure a model

Example:

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

Then set the corresponding API keys in .env.

The public model identity stays as the gateway model even when a request is routed to another upstream provider.

Claude Code

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

Or:

python -m my_free_code.cli.mfc claude

Other clients

The launcher abstraction supports:

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

The installed client must already exist on PATH.

Routing and fallback

For:

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

a Sonnet request follows:

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | failure before output
    v
groq/llama-3.3-70b-versatile
    |
    | failure before output
    v
ollama/llama3.1

Once a streaming response has committed output, the gateway does not silently switch providers and duplicate the turn.

Reasoning

The gateway accepts Claude-style thinking intent and keeps it separate from provider-specific request translation.

Supported normalized modes:

auto
on
off

and optional effort:

low
medium
high

Provider adapters can map the normalized reasoning policy to their documented upstream fields.

Admin

Open:

http://127.0.0.1:8082/admin

Authenticated JSON endpoints:

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

Local models

Ollama:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

LM Studio:

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp:

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

Security

This is intended for local use.

Tests

pytest -q

The repository includes deterministic tests for routing, protocol conversion, auth, reasoning, model catalog and streaming primitives.

Project structure

my-free-code/
├── my_free_code/
│   ├── api/
│   │   ├── routes.py
│   │   └── admin_routes.py
│   ├── cli/
│   │   ├── claude.py
│   │   ├── launchers.py
│   │   └── mfc.py
│   ├── core/
│   │   ├── anthropic.py
│   │   ├── responses.py
│   │   ├── reasoning.py
│   │   ├── failures.py
│   │   ├── streaming.py
│   │   └── model_catalog.py
│   └── providers/
│       ├── catalog.py
│       ├── adapters.py
│       ├── specialized.py
│       └── runtime.py
├── tests/
├── ARCHITECTURE.md
├── .env.example
├── requirements.txt
├── pyproject.toml
└── README.md

License

MIT.

my-free-code (hkqr/my-free-code)

Searching Database…

624 ·GitHub
My-free-code
Что это?My Free Code — open-source шлюз, который стоит между кодинг-агентами вроде Claude Code и десятками провайдеров LLM и занимается маршрутизацией моделей, стримингом, вызовами инструментов, прозрачной передачей reasoning и переключением на резервного провайдера.
Это библиотека для импорта или сервер, который я запускаю локально?Это самостоятельный локальный сервер, который вы запускаете сами: он открывает HTTP-эндпоинты, совместимые с Anthropic Messages и OpenAI Responses, плюс локальный Admin UI, а не библиотека, которую вы импортируете в код.
Как его запустить?Установите Python 3.10+, затем запустите входящий в комплект стартовый скрипт для Windows или macOS/Linux; он поднимет прокси на локальном адресе по умолчанию, на который затем направляется ваш кодинг-агент.
Нужны ли API-ключи для каждого провайдера из каталога?Нет, только для провайдеров, к которым вы действительно хотите направлять запросы — эти ключи добавляются в ваш файл .env; каталог простирается от облачных провайдеров вроде OpenAI и OpenRouter до локальных рантаймов вроде Ollama и llama.cpp.
Переключит ли он провайдера молча, если один даст сбой посреди ответа?Нет. Резерв включается только до того, как ответ начал передаваться потоком; когда вывод уже пошёл, шлюз не переключит провайдера и не будет дублировать ход.
Безопасно ли выставлять это в интернет?Нет, он создан только для локального использования — привяжите хост к 127.0.0.1, задайте настоящий токен авторизации и никогда не открывайте Admin-эндпоинты напрямую в интернет.
Каких кодинг-агентов можно запускать через этот шлюз?Есть адаптеры запуска для Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build и Muse Code; каждый лаунчер лишь готовит окружение локального прокси и делегирует уже установленному клиенту.
Можно запускать полностью локальные модели вместо облачных провайдеров?Да — Ollama, LM Studio и llama.cpp поддерживаются как провайдеры, так что запросы можно направлять локально размещённым моделям вместе с облачными или вместо них.
Поддерживается ли режим reasoning/thinking Claude?Да, он принимает интент размышления в стиле Claude, нормализует его в общие reasoning-режимы с опциональным уровнем усилий, а адаптеры провайдеров отображают это в собственные thinking-поля каждого провайдера.
Утекают ли мои учётные данные провайдера к другим провайдерам?Нет — учётные данные остаются в вашей локальной среде/конфигурации отдельно для каждого провайдера и никогда не пересылаются другому провайдеру.
What are similar projects?gpt-load, casbin-gateway, ThinkWatch-Lite, OmniRoute, monid, opencodex, router, sub2api
Which topics is it in?multi-provider, llm-gateway, ai-gateway, tool-calling, api-gateway, local-llm, ollama, streaming, proxy, coding-agent, openai, codex
Creator
hkqr
Size
0.7 MB
Stars
624
Updated
CommitOct 17
Age
1mo
Commits · 90 Days