The Problem

Developers who want Claude Code, Codex or Pi locally must juggle separate CLI tools, browser‑only UI extensions, and ad‑hoc proxy scripts. Keeping the provider list, model routing, and voice‑note transcription in sync is error‑prone and often requires manual environment tweaks.

What This Does

free‑claude‑code bundles a self‑hosted proxy that exposes the Claude, Codex and Pi APIs through a single HTTP server. The server lives in src/free_claude_code/api/app.py and is started by the CLI entry point fcc‑server (installed by the provided install scripts).

Provider configuration, model catalogues and admin UI assets are defined under src/free_claude_code/config/ and src/free_claude_code/api/admin_static/. The voice‑enabled workflow lives in src/free_claude_code/messaging/voice.py and is wired through src/free_claude_code/messaging/platforms/voice_flow.py.

The test harness in smoke/lib/e2e.py validates end‑to‑end behavior, while the extensive tests/ package supplies unit coverage for request handling, model selection and streaming logic.

How It Is Wired

Execution begins at the entry point smoke/lib/e2e.py → start (line 319). start creates a temporary server (run → start_server) that writes log files (config.results_dir.mkdir) and spawns a subprocess (subprocess.Popen). The server process loads configuration via smoke/lib/config.py (calls load, model_name, provider_models).

The HTTP service itself is defined in src/free_claude_code/api/app.py. The global exception handlers general_error_handler, application_error_handler and validation_error_handler are the only callers of the corresponding functions, limiting their blast radius.

Core request handling flows through the hub modules identified by the import graph:

  • tests/providers/support – imported by 36 modules.
  • smoke/lib/config – imported by 30 modules.
  • tests/providers/request_factory – imported by 24 modules.

These hubs host volatile test fixtures; changes here ripple widely, so keep them stable.

Message processing travels src/free_claude_code/messaging/workflow.py → src/free_claude_code/messaging/models → src/free_claude_code/core/anthropic/*. The most‑used internal symbols are Settings (113 callers) and create_test_app (73 callers).

A circular import exists among src/free_claude_code/core/openai_responses/streaming/__init__.py, src/free_claude_code/api/web_tools/__init__.py and src/free_claude_code/api/web_tools/streaming.py; breaking this cycle will simplify refactoring.

External interactions are concentrated in a few places:

  • Filesystem I/O – 168 functions (e.g., download_to in src/free_claude_code/messaging/platforms/voice_flow.py).
  • Network calls – 119 functions (e.g., make_request in src/free_claude_code/application/ports.py).
  • Subprocess launch – run → start_server in smoke/lib/e2e.py.

No other external effects (e.g., database) are traced.

How To Use It

# Install / update (macOS / Linux)
curl -fsSL "https://raw.githubusercontent.com/moses-y/free-claude-code/main/scripts/install.sh" | sh

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

The installer registers the fcc‑server binary and desktop launchers (fcc‑claude, fcc‑codex, fcc‑pi).

Configuration is read from .env.example; copy it to .env and adjust FCC_ADMIN_PASSWORD, FCC_MODEL_CATALOG_PATH, etc., as required by src/free_claude_code/config/env_template.py.

Start the proxy:

fcc-server          # runs the FastAPI app on localhost:8000

The Admin UI is served at http://localhost:8000/admin/ (static files in src/free_claude_code/api/admin_static/). CLI commands (fcc-claude, fcc-codex, fcc-pi) automatically target the local proxy.

Real‑World Use

A CI pipeline can invoke fcc‑claude to generate code suggestions for PRs, while developers use the VS Code extension to fetch completions from the locally routed Claude model. Voice notes from a Slack bot are transcribed via src/free_claude_code/messaging/voice.py, sent to the proxy, and the resulting assistant reply is posted back to the channel—all without leaving the corporate network.

Code Health & Issues

  • Medium – Dependency‑vulnerability gate missing – .github/workflows/tests.yml lacks a scan step.
  • Low – Repository conventions missing – No .editorconfig, .gitattributes or formatter config.

Measured static findings (29 high, 108 medium, 0 low) include:

  • High/clarity – Hub modules (tests/providers/support.py, smoke/lib/config.py, tests/providers/request_factory.py) – each imported by >30 files; keep them small.
  • High/soundness – Import cycles – 5 modules (e.g., src/free_claude_code/core/openai_responses/streaming/__init__.py).
  • High/cognitive_load – Deep nesting – 31 occurrences, max depth 7 (e.g., smoke/lib/e2e.py).
  • Medium/resource_safety – Files opened without context – smoke/lib/e2e.py.
  • Medium/resilience – Broad exception handling – 11 modules swallow generic Exception.

No lockfile is present; builds are non‑reproducible. The openai dependency is pinned to >=2.46.0 while the latest major version is 3.x.

The Bottom Line

free‑claude‑code delivers a functional, locally hosted proxy for Anthropic‑ and OpenAI‑based coding agents, with a usable admin UI and voice integration. The codebase is sizable and contains several high‑impact hubs and a few circular imports that will increase maintenance cost. It is suitable for teams comfortable managing Python environments and willing to address the missing CI security gate and repository conventions.