Skip to content

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.md
index 075fc7f9..3df5d329 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -119,6 +119,14 @@ server does not require an optional extra. Static AST enforcement cannot observe
dynamic imports. Deliberate provider factory loading is instead protected by the
provider 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 and
shared protocol behavior belong in [src/free_claude_code/core/](src/free_claude_code/core/), while request routing and
provider execution belong in [src/free_claude_code/application/](src/free_claude_code/application/). Routes use core schemas
diff --git a/README.md b/README.md
index 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 installe
fcc-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:
```text
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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.py
index 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.py
index 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.py
index 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 pytest
from free_claude_code.cli.managed.manager import ManagedClaudeSessionManager
from 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_text
from smoke.lib.config import SmokeConfig
pytestmark = [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.asyncio
async 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.py
index 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_version
from .admin_routes import router as admin_router
from .ports import ApiServices
@@ -35,7 +36,7 @@ from .validation_log import summarize_request_validation_body
def 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.py
index 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.py
index c3ba60b0..c3d41b52 100644
--- a/src/free_claude_code/cli/entrypoints.py
+++ b/src/free_claude_code/cli/entrypoints.py
@@ -6,6 +6,7 @@ import sys
import threading
import time
import webbrowser
+from collections.abc import Sequence
from pathlib import Path
import 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_url
from free_claude_code.config.settings import Settings, get_settings
+from free_claude_code.core.version import package_version
from free_claude_code.runtime.bootstrap import build_asgi_app
SERVER_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):
+ return
opened_admin_browser = False
try:
try:
@@ -109,8 +113,10 @@ def _run_supervised_server(settings: Settings, *, open_admin_browser: bool) -> b
return 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):
+ return
config_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.py
new file mode 100644
index 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_VERSION
diff --git a/tests/api/test_app_version.py b/tests/api/test_app_version.py
new file mode 100644
index 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.py
index 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_version
from 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.py
index 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.py
new file mode 100644
index 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.lock
index 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" },