Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Use installed metadata as the single package version source (#1051)
Ali Khokhar26cc73e6ced7
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 075fc7f9..3df5d329 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -119,6 +119,14 @@ server does not require an optional extra. Static AST enforcement cannot observedynamic imports. Deliberate provider factory loading is instead protected by theprovider catalog, supported-ID, and factory synchronization contract.+[core/version.py](src/free_claude_code/core/version.py) is the sole runtime owner+of the FCC release version. It reads installed distribution metadata for+FastAPI/OpenAPI, FCC-owned CLI `--version` output, and the outbound web-tools+user agent. A source-only checkout without installed metadata reports the+explicit `0+unknown` fallback; runtime code never parses `pyproject.toml` or+duplicates a release literal. Claude and Codex launcher arguments remain+transparent to their wrapped clients.+The main ownership rule is that Anthropic and Responses protocol schemas andshared protocol behavior belong in [src/free_claude_code/core/](src/free_claude_code/core/), while request routing andprovider execution belong in [src/free_claude_code/application/](src/free_claude_code/application/). Routes use core schemasdiff --git a/README.md b/README.mdindex c36a1f56..47204623 100644--- a/README.md+++ b/README.md@@ -91,6 +91,9 @@ Re-run the same command whenever you want to update. You can review the installefcc-server```+To print the installed Free Claude Code version without starting the server,+run `fcc-server --version`.+Keep this process running. The startup log shows the Admin UI address:```textdiff --git a/pyproject.toml b/pyproject.tomlindex 4c1f419d..9d841243 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "3.4.24"+version = "3.5.0"description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"readme = "README.md"requires-python = ">=3.14.0"diff --git a/smoke/capabilities.py b/smoke/capabilities.pyindex 17a8985d..cb0f1db3 100644--- a/smoke/capabilities.py+++ b/smoke/capabilities.py@@ -447,12 +447,13 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = ("package_cli_entrypoints","free_claude_code.cli.entrypoints","installed console scripts",- "config scaffold or uvicorn server startup",+ "config scaffold, package version, or uvicorn server startup","process cleanup in finally",- ("tests/cli/test_entrypoints.py",),+ ("tests/cli/test_entrypoints.py", "tests/core/test_version.py"),("test_fcc_init_scaffolds_user_config","test_free_claude_code_entrypoint_starts_server",+ "test_entrypoint_version_e2e",),),CapabilityContract(diff --git a/smoke/features.py b/smoke/features.pyindex 16ba1ef0..74f7b171 100644--- a/smoke/features.py+++ b/smoke/features.py@@ -399,14 +399,18 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (),FeatureCoverage("package_cli_entrypoints",- "Installed package scripts scaffold config and start the server",+ "Installed package scripts scaffold config, report version, and start the server","public_surface",- ("tests/cli/test_entrypoints.py",),+ ("tests/cli/test_entrypoints.py", "tests/core/test_version.py"),("test_fcc_init_scaffolds_user_config","test_free_claude_code_entrypoint_starts_server",),- ("test_entrypoint_init_e2e", "test_entrypoint_server_e2e"),+ (+ "test_entrypoint_init_e2e",+ "test_entrypoint_server_e2e",+ "test_entrypoint_version_e2e",+ ),("cli",),(),"always runnable once uv project dependencies are available",diff --git a/smoke/lib/child_process.py b/smoke/lib/child_process.pyindex a1fecd11..79e5dc3c 100644--- a/smoke/lib/child_process.py+++ b/smoke/lib/child_process.py@@ -28,6 +28,18 @@ def cmd_fcc_init() -> list[str]:]+def cmd_fcc_version() -> list[str]:+ return [+ python_exe(),+ "-c",+ (+ "import sys; "+ "sys.argv = ['fcc-server', '--version']; "+ "from free_claude_code.cli.entrypoints import serve; serve()"+ ),+ ]++def cmd_free_claude_code_serve() -> list[str]:return [python_exe(),diff --git a/smoke/product/test_cli_package_product_live.py b/smoke/product/test_cli_package_product_live.pyindex 400af0f3..67f6693b 100644--- a/smoke/product/test_cli_package_product_live.py+++ b/smoke/product/test_cli_package_product_live.py@@ -7,7 +7,8 @@ import pytestfrom free_claude_code.cli.managed.manager import ManagedClaudeSessionManagerfrom free_claude_code.cli.managed.session import ManagedClaudeSession-from smoke.lib.child_process import cmd_fcc_init, run_captured_text+from free_claude_code.core.version import package_version+from smoke.lib.child_process import cmd_fcc_init, cmd_fcc_version, run_captured_textfrom smoke.lib.config import SmokeConfigpytestmark = [pytest.mark.live, pytest.mark.smoke_target("cli")]@@ -30,6 +31,25 @@ def test_entrypoint_init_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:assert env_file.read_text(encoding="utf-8").strip()+def test_entrypoint_version_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> None:+ env = os.environ.copy()+ env["HOME"] = str(tmp_path)+ env["USERPROFILE"] = str(tmp_path)++ result = run_captured_text(+ cmd_fcc_version(),+ cwd=smoke_config.root,+ env=env,+ timeout=smoke_config.timeout_s,+ check=False,+ )++ assert result.returncode == 0+ assert result.stdout == f"free-claude-code {package_version()}\n"+ assert result.stderr == ""+ assert not (tmp_path / ".fcc" / ".env").exists()++@pytest.mark.asyncioasync def test_cli_session_resume_fork_e2e(tmp_path: Path) -> None:session = ManagedClaudeSession(str(tmp_path), "http://127.0.0.1:8082/v1")diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.pyindex 914ac951..b3349413 100644--- a/src/free_claude_code/api/app.py+++ b/src/free_claude_code/api/app.py@@ -19,6 +19,7 @@ from free_claude_code.core.trace import (extract_claude_session_id_from_headers,trace_event,)+from free_claude_code.core.version import package_versionfrom .admin_routes import router as admin_routerfrom .ports import ApiServices@@ -35,7 +36,7 @@ from .validation_log import summarize_request_validation_bodydef create_app(services: ApiServices) -> FastAPI:"""Create the HTTP adapter around explicitly supplied runtime services."""- app = FastAPI(title="Claude Code Proxy", version="2.1.0")+ app = FastAPI(title="Claude Code Proxy", version=package_version())app.state.services = services@app.middleware("http")diff --git a/src/free_claude_code/api/web_tools/constants.py b/src/free_claude_code/api/web_tools/constants.pyindex e7b2c017..db6546a6 100644--- a/src/free_claude_code/api/web_tools/constants.py+++ b/src/free_claude_code/api/web_tools/constants.py@@ -1,5 +1,7 @@"""Limits and defaults for outbound web server tool HTTP."""+from free_claude_code.core.version import package_version+_REQUEST_TIMEOUT_S = 20.0_MAX_SEARCH_RESULTS = 10_MAX_FETCH_CHARS = 24_000@@ -11,5 +13,5 @@ _MAX_WEB_FETCH_REDIRECTS = 10_WEB_FETCH_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})_WEB_TOOL_HTTP_HEADERS = {- "User-Agent": "Mozilla/5.0 compatible; free-claude-code/2.0",+ "User-Agent": f"Mozilla/5.0 compatible; free-claude-code/{package_version()}",}diff --git a/src/free_claude_code/cli/entrypoints.py b/src/free_claude_code/cli/entrypoints.pyindex c3ba60b0..c3d41b52 100644--- a/src/free_claude_code/cli/entrypoints.py+++ b/src/free_claude_code/cli/entrypoints.py@@ -6,6 +6,7 @@ import sysimport threadingimport timeimport webbrowser+from collections.abc import Sequencefrom pathlib import Pathimport uvicorn@@ -26,13 +27,16 @@ from free_claude_code.config.paths import ()from free_claude_code.config.server_urls import local_admin_url, local_proxy_root_urlfrom free_claude_code.config.settings import Settings, get_settings+from free_claude_code.core.version import package_versionfrom free_claude_code.runtime.bootstrap import build_asgi_appSERVER_GRACEFUL_SHUTDOWN_SECONDS = 5-def serve() -> None:+def serve(argv: Sequence[str] | None = None) -> None:"""Start the FastAPI server (registered as `fcc-server` script)."""+ if _print_version_if_requested(argv):+ returnopened_admin_browser = Falsetry:try:@@ -109,8 +113,10 @@ def _run_supervised_server(settings: Settings, *, open_admin_browser: bool) -> breturn restart_requested-def init() -> None:+def init(argv: Sequence[str] | None = None) -> None:"""Scaffold config at ~/.fcc/.env (registered as `fcc-init`)."""+ if _print_version_if_requested(argv):+ returnconfig_dir = config_dir_path()env_file = managed_env_path()@@ -135,6 +141,14 @@ def init() -> None:print("Edit it to set your API keys and model preferences, then run: fcc-server")+def _print_version_if_requested(argv: Sequence[str] | None) -> bool:+ args = sys.argv[1:] if argv is None else argv+ if "--version" not in args:+ return False+ print(f"free-claude-code {package_version()}")+ return True++def _migrate_legacy_env_if_missing() -> Path | None:"""Copy a legacy user env into the managed config path when absent."""diff --git a/src/free_claude_code/core/version.py b/src/free_claude_code/core/version.pynew file mode 100644index 00000000..42a122cf--- /dev/null+++ b/src/free_claude_code/core/version.py@@ -0,0 +1,15 @@+"""Canonical installed Free Claude Code package version."""++from importlib.metadata import PackageNotFoundError+from importlib.metadata import version as distribution_version++_DISTRIBUTION_NAME = "free-claude-code"+_UNKNOWN_VERSION = "0+unknown"+++def package_version() -> str:+ """Return installed metadata, or an explicit source-only fallback."""+ try:+ return distribution_version(_DISTRIBUTION_NAME)+ except PackageNotFoundError:+ return _UNKNOWN_VERSIONdiff --git a/tests/api/test_app_version.py b/tests/api/test_app_version.pynew file mode 100644index 00000000..7c02e463--- /dev/null+++ b/tests/api/test_app_version.py@@ -0,0 +1,21 @@+import warnings++from fastapi.testclient import TestClient++from free_claude_code.core.version import package_version+from tests.api.support import create_test_app+++def test_fastapi_and_openapi_report_installed_package_version() -> None:+ app = create_test_app()++ assert app.version == package_version()+ with warnings.catch_warnings():+ warnings.filterwarnings(+ "ignore",+ message="Duplicate Operation ID",+ category=UserWarning,+ )+ response = TestClient(app).get("/openapi.json")+ assert response.status_code == 200+ assert response.json()["info"]["version"] == package_version()diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.pyindex 1fe48420..46d22eab 100644--- a/tests/api/test_web_server_tools.py+++ b/tests/api/test_web_server_tools.py@@ -38,6 +38,7 @@ from free_claude_code.core.anthropic.stream_contracts import (parse_sse_text,text_content,)+from free_claude_code.core.version import package_versionfrom free_claude_code.messaging.event_parser import parse_cli_event_STRICT_EGRESS = WebFetchEgressPolicy(@@ -56,6 +57,12 @@ _SERVER_TOOL_PASSTHROUGH_PROVIDER_IDS = tuple()+def test_web_tool_user_agent_reports_installed_package_version() -> None:+ assert {+ "User-Agent": (f"Mozilla/5.0 compatible; free-claude-code/{package_version()}")+ } == web_tool_constants._WEB_TOOL_HTTP_HEADERS++class FixedProviderModelRouter(ModelRouter):"""Test double: pin provider identity and semantic capabilities."""diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.pyindex c241db22..6aa502fe 100644--- a/tests/cli/test_entrypoints.py+++ b/tests/cli/test_entrypoints.py@@ -179,6 +179,47 @@ def test_cli_scripts_are_registered() -> None:assert scripts["fcc-codex"] == "free_claude_code.cli.launchers.codex:launch"[email protected]("entrypoint_name", ["serve", "init"])+ "argv",+ [("--version",), ("--version", "--help"), ("--help", "--version")],+)+def test_fcc_owned_entrypoints_report_version_without_side_effects(+ entrypoint_name: str,+ argv: tuple[str, ...],+ capsys: pytest.CaptureFixture[str],+) -> None:+ from free_claude_code.cli import entrypoints++ with (+ patch.object(entrypoints, "package_version", return_value="9.8.7"),+ patch.object(entrypoints, "_migrate_legacy_env_if_missing") as migrate_legacy,+ patch.object(entrypoints, "_migrate_config_env_keys") as migrate_keys,+ patch.object(entrypoints, "get_settings") as get_settings,+ patch.object(+ entrypoints, "_run_supervised_server", return_value=False+ ) as run_server,+ patch.object(entrypoints, "kill_all_best_effort") as kill_all,+ patch.object(entrypoints, "config_dir_path") as config_dir,+ patch.object(entrypoints, "managed_env_path") as managed_env,+ patch.object(entrypoints, "load_env_template") as load_template,+ ):+ getattr(entrypoints, entrypoint_name)(argv)++ assert capsys.readouterr() == ("free-claude-code 9.8.7\n", "")+ for side_effect in {+ migrate_legacy,+ migrate_keys,+ get_settings,+ run_server,+ kill_all,+ config_dir,+ managed_env,+ load_template,+ }:+ side_effect.assert_not_called()++def test_schedule_open_admin_browser_opens_when_health_ready(monkeypatch: pytest.MonkeyPatch,) -> None:diff --git a/tests/core/test_version.py b/tests/core/test_version.pynew file mode 100644index 00000000..084409bb--- /dev/null+++ b/tests/core/test_version.py@@ -0,0 +1,42 @@+import tomllib+from importlib.metadata import PackageNotFoundError+from importlib.metadata import version as distribution_version+from pathlib import Path++import pytest++import free_claude_code.core.version as version_module+++def test_package_version_uses_installed_distribution_metadata() -> None:+ assert version_module.package_version() == distribution_version("free-claude-code")+++def test_package_version_has_explicit_uninstalled_source_fallback(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def missing(_distribution_name: str) -> str:+ raise PackageNotFoundError("free-claude-code")++ monkeypatch.setattr(version_module, "distribution_version", missing)++ assert version_module.package_version() == "0+unknown"+++def test_package_version_does_not_hide_invalid_installed_metadata(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ def invalid(_distribution_name: str) -> str:+ raise ValueError("invalid metadata")++ monkeypatch.setattr(version_module, "distribution_version", invalid)++ with pytest.raises(ValueError, match="invalid metadata"):+ version_module.package_version()+++def test_project_release_version_matches_installed_metadata() -> None:+ repo_root = Path(__file__).resolve().parents[2]+ pyproject = tomllib.loads((repo_root / "pyproject.toml").read_text("utf-8"))++ assert pyproject["project"]["version"] == distribution_version("free-claude-code")diff --git a/uv.lock b/uv.lockindex 34ea8af2..1eb909f0 100644--- a/uv.lock+++ b/uv.lock@@ -561,7 +561,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "3.4.24"+version = "3.5.0"source = { editable = "." }dependencies = [{ name = "aiohttp" },