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

Simplify README around customer workflows (#1345)

Ali Khokharacadf308c4f1
diff --git a/README.md b/README.md
index 6e4c95b9..eb224957 100644
--- a/README.md
+++ b/README.md
@@ -7,56 +7,32 @@
</picture>
</h1>
-Use Claude Code, Codex, Pi, or their IDE extensions through your own provider-backed proxy.
-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Python 3.14](https://img.shields.io/badge/python-3.14-3776ab.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge)](https://github.com/astral-sh/uv)
-[![Tested with Pytest](https://img.shields.io/badge/testing-Pytest-00c0ff.svg?style=for-the-badge)](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)
+[![Testing: Pytest](https://img.shields.io/badge/Testing-Pytest-00c0ff.svg?style=for-the-badge)](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)
[![Type checking: Ty](https://img.shields.io/badge/type%20checking-ty-ffcc00.svg?style=for-the-badge)](https://pypi.org/project/ty/)
[![Code style: Ruff](https://img.shields.io/badge/code%20formatting-ruff-f5a623.svg?style=for-the-badge)](https://github.com/astral-sh/ruff)
[![Logging: Loguru](https://img.shields.io/badge/logging-loguru-4ecdc4.svg?style=for-the-badge)](https://github.com/Delgan/loguru)
-Run your coding agents with free, paid, or local models. Choose and validate providers from one local Admin UI.
-
[Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-your-client) · [Integrations](#optional-integrations) · [Manage](#manage-your-installation)
</div>
-<div align="center">
- <img src="assets/pic.png" alt="Free Claude Code in action" width="700">
- <p><em>Claude Code running through the Free Claude Code proxy.</em></p>
-</div>
-
-<div align="center">
- <img src="assets/codex.png" alt="Codex CLI in action through Free Claude Code" width="700">
- <p><em>Codex CLI using the local FCC Responses provider.</em></p>
-</div>
-
-<a id="model-picker"></a>
+## What You Get
-<div align="center">
- <img src="assets/cc-model-picker.png" alt="Claude Code model picker showing gateway models" width="700">
- <p><em>Claude Code native <code>/model</code> picker with FCC gateway models.</em></p>
-</div>
+- **Use your preferred coding agent.** Run Claude Code, Codex, or Pi with FCC.
+- **Choose your own models.** Connect free, paid, or local providers and search their models from one Admin UI.
+- **Route work your way.** Set one default model or map Fable, Opus, Sonnet, and Haiku separately.
+- **Save time and tokens.** Five built-in optimizations handle quota probes, command-prefix detection, title generation, suggestion mode, and filepath extraction locally instead of calling your provider.
+- **Keep coding-agent capabilities.** Use streaming, tools, reasoning, and image input with compatible models.
+- **Work where you want.** Launch from your desktop, connect supported IDEs, or use optional Discord and Telegram bots with voice notes.
<div align="center">
- <img src="assets/codex-model-picker.png" alt="Codex model picker showing generated FCC model catalog" width="700">
- <p><em>Codex native <code>/model</code> picker with the generated FCC catalog.</em></p>
+ <img src="assets/pic.png" alt="Claude Code running with Free Claude Code" width="700">
+ <p><em>Claude Code running with FCC.</em></p>
</div>
-## What You Get
-
-- Launch Claude Code with `fcc-claude`, Codex with `fcc-codex`, or Pi with `fcc-pi`.
-- Run FCC in the background from a desktop launcher on Windows or macOS.
-- Switch among 31 cloud and local providers from the Admin UI.
-- Use each coding agent's native model picker.
-- Route Fable, Opus, Sonnet, Haiku, and fallback traffic to different models.
-- Keep streaming, tool use, reasoning, and image input across compatible models.
-- Connect Claude Code and Codex in VS Code or Claude Code through JetBrains ACP.
-- Optionally run Claude Code sessions through Discord or Telegram with voice-note transcription.
-- Protect the local proxy with optional token authentication.
-
## Quick Start
<a id="install"></a>
@@ -105,8 +81,7 @@ To print the installed Free Claude Code version without starting the server,
run `fcc-server --version`.
When using `fcc-server`, keep the terminal open. The Admin UI opens in your
-browser once the server is healthy by default. Its address is shown in the
-startup log:
+browser after startup by default. Its address is also shown in the log:
```text
INFO: Admin UI: http://127.0.0.1:8082/admin (local-only)
@@ -125,7 +100,7 @@ Use the port shown in your terminal if it differs from `8082`.
5. Click **Validate**, then **Apply**.
<div align="center">
- <img src="assets/admin-page.png" alt="Local admin UI for proxy settings" width="700">
+ <img src="assets/admin-page.png" alt="Free Claude Code Admin UI" width="700">
</div>
### 4. Run Your Coding Agent
@@ -156,6 +131,13 @@ fcc-codex exec "hello"
`fcc-pi` registers FCC only for that Pi process; your existing Pi settings, sessions, credentials, and extensions remain unchanged.
+<a id="model-picker"></a>
+
+<div align="center">
+ <img src="assets/cc-model-picker.png" alt="Claude Code model picker showing FCC models" width="700">
+ <p><em>Select an FCC model from Claude Code's native <code>/model</code> picker.</em></p>
+</div>
+
## Choose A Provider
1. Open a provider link below for its key, models, or setup instructions.
@@ -165,6 +147,9 @@ fcc-codex exec "hello"
models, enter `<provider-id>/<exact-provider-model-id>` manually.
4. Click **Validate**, then **Apply**.
+<details>
+<summary><strong>Provider catalog</strong></summary>
+
| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
| [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
@@ -199,39 +184,38 @@ fcc-codex exec "hello"
| [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/<model-id>` |
| [Ollama](https://ollama.com/) | `OLLAMA_BASE_URL` | `ollama/<model-tag>` |
-Important provider notes:
+</details>
+
+<details>
+<summary><strong>Provider-specific setup</strong></summary>
- OpenAI uses your ChatGPT subscription rather than an API key. Connect from
- **Providers → Connected accounts**; browser PKCE is the default and device
- code is available for headless setups. FCC stores its own renewable
- credentials under `~/.fcc/auth/` and leaves Codex login untouched. Restart
- an already-running agent after connecting to refresh its model picker.
+ **Providers → Connected accounts** in the Admin UI. Use device code on
+ headless systems. Restart an already-running agent after connecting.
- Azure OpenAI uses the deployment names from your resource. Set
`AZURE_OPENAI_BASE_URL` to its complete v1 endpoint, such as
`https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`, and select a
- deployment that supports Chat Completions. Azure does not expose custom
- deployment names through its data-plane model list, so enter the deployment
- name as a custom model slug.
+ deployment that supports Chat Completions. Enter the deployment name as a
+ custom model slug if it does not appear in the model dropdown.
- Mistral Codestral uses a separate key from Mistral La Plateforme.
- Kimi Code subscription keys use `kimi_code/`; Kimi API credit keys use
`kimi/`. Kimi Code plans are for personal interactive coding-agent use under
[Kimi's community guidelines](https://www.kimi.com/code/docs/en/kimi-code/community-guidelines.html).
- OpenCode Zen and OpenCode Go share `OPENCODE_API_KEY` but use the explicit
`opencode_zen/` and `opencode_go/` model prefixes.
-- Amazon Bedrock uses its Mantle OpenAI-compatible endpoint. Set
- `BEDROCK_BASE_URL` to the endpoint for the same region as the API key and
- select one of the models returned by FCC's model picker.
+- For Amazon Bedrock, set `BEDROCK_BASE_URL` to the URL for the same region as
+ the API key and select one of the listed models.
- Vertex AI uses Google Application Default Credentials instead of an API key.
Locally, run `gcloud auth application-default login` once; service-account
files and attached service accounts also work. Set `VERTEX_PROJECT_ID`, and
- optionally change `VERTEX_LOCATION` from its `global` default. FCC refreshes
- expiring access tokens automatically.
+ optionally change `VERTEX_LOCATION` from its `global` default.
- Cloudflare requires both its API token and account ID.
-- Ollama Cloud connects directly to `ollama.com`; use the exact model IDs shown
- by FCC's model picker. Local Ollama remains available through the separate
- `ollama/` prefix.
+- For Ollama Cloud, use the exact model IDs shown in the model picker. Local
+ Ollama uses the separate `ollama/` prefix.
- Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.
+</details>
+
<details>
<summary><strong>Local provider setup</strong></summary>
@@ -254,13 +238,17 @@ Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL`
</details>
-### Optional Model-Tier Routing
+<details>
+<summary><strong>Optional model-tier routing</strong></summary>
`MODEL` is the fallback for every request. Select a model for `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override an individual Claude Code tier; select **None** to use `MODEL`.
For example, route Opus to `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, Sonnet to `open_router/openrouter/free`, Haiku to `lmstudio/qwen3.5-coder`, and keep `MODEL` on `zai/glm-5.2`.
-### Reasoning Control
+</details>
+
+<details>
+<summary><strong>Reasoning control</strong></summary>
Open **Admin UI → Model Config → Reasoning** and select the behavior you want.
@@ -273,6 +261,8 @@ Open **Admin UI → Model Config → Reasoning** and select the behavior you wan
Providers that do not support a selected control retain their own behavior.
+</details>
+
<a id="connect-your-client"></a>
## Connect Your Client
@@ -304,28 +294,30 @@ Match the port and authentication token to the Admin UI, then reload the extensi
<details>
<summary><strong>Codex App</strong></summary>
-Start FCC, then add its provider and generated model catalog to your user-level Codex configuration.
+Start FCC, then edit your Codex configuration:
+
+- Windows: `%USERPROFILE%\.codex\config.toml`
+- macOS: `~/.codex/config.toml`
-**Windows** — edit `%USERPROFILE%\.codex\config.toml` and replace `YOUR_USERNAME`:
+Add the matching model-catalog path and replace `YOUR_USERNAME`.
+
+Windows:
```toml
-model_provider = "fcc"
-model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
model_catalog_json = "C:/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"
+```
-[model_providers.fcc]
-name = "Free Claude Code"
-base_url = "http://127.0.0.1:8082/v1"
-http_headers = { Authorization = "Bearer freecc" }
-wire_api = "responses"
+macOS:
+
+```toml
+model_catalog_json = "/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"
```
-**macOS** — edit `~/.codex/config.toml` and replace `YOUR_USERNAME`:
+Then add the shared FCC settings:
```toml
model_provider = "fcc"
model = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
-model_catalog_json = "/Users/YOUR_USERNAME/.fcc/codex-model-catalog.json"
[model_providers.fcc]
name = "Free Claude Code"
@@ -334,7 +326,8 @@ http_headers = { Authorization = "Bearer freecc" }
wire_api = "responses"
```
-Match the model, port, and bearer token to the Admin UI. Restart the Codex App after setup or model changes, then use its model picker to select any FCC provider/model slug.
+Match the model, port, and bearer token to the Admin UI. Restart the Codex App
+after setup or model changes, then select an FCC model from its model picker.
</details>
@@ -416,10 +409,6 @@ Restart Claude Code or the IDE after saving the file.
Configure integrations from **Admin UI → Messaging**, then click **Validate** and **Apply**.
-<div align="center">
- <img src="assets/admin-messaging.png" alt="Admin UI Messaging view with bot and voice settings" width="700">
-</div>
-
<details>
<summary><strong>Discord bot</strong></summary>
@@ -458,38 +447,28 @@ Configure integrations from **Admin UI → Messaging**, then click **Validate**
<details>
<summary><strong>Voice notes</strong></summary>
-Re-run the installer with the voice backend you need.
+Choose the voice backend you want, then re-run the installer with its option.
+
+| Voice backend | macOS/Linux option | Windows option |
+| --- | --- | --- |
+| NVIDIA NIM transcription | `--voice-nim` | `-VoiceNim` |
+| Local Whisper on CPU or CUDA | `--voice-local` | `-VoiceLocal` |
+| Both backends | `--voice-all` | `-VoiceAll` |
+| Local Whisper with CUDA 13.0 | `--voice-local --torch-backend cu130` | `-VoiceLocal -TorchBackend cu130` |
+
+The examples below install NVIDIA NIM transcription. To use another backend,
+replace the final option with the matching one from the table.
macOS/Linux:
```bash
-# NVIDIA NIM transcription
curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-nim
-
-# Local Whisper on CPU or CUDA
-curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local
-
-# Both backends
-curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-all
-
-# Local Whisper with the CUDA 13.0 PyTorch backend
-curl -fsSL "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.sh" | sh -s -- --voice-local --torch-backend cu130
```
Windows PowerShell:
```powershell
-# NVIDIA NIM transcription
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceNim
-
-# Local Whisper on CPU or CUDA
-& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal
-
-# Both backends
-& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceAll
-
-# Local Whisper with the CUDA 13.0 PyTorch backend
-& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Alishahryar1/free-claude-code/main/scripts/install.ps1"))) -VoiceLocal -TorchBackend cu130
```
Restart `fcc-server`. In **Admin UI → Messaging → Voice**, enable voice notes, select `cpu`, `cuda`, or `nvidia_nim`, and choose the Whisper model. Local gated models need `HUGGINGFACE_API_KEY`; NVIDIA NIM transcription needs `NVIDIA_NIM_API_KEY`.
@@ -504,8 +483,7 @@ Re-run the matching command from [Install Or Update](#install).
### Uninstall
-Stop every running FCC command first. The uninstaller verifies every FCC command is gone
-before deleting its managed data.
+Stop every running FCC command before uninstalling.
**Removes**
diff --git a/smoke/features.py b/smoke/features.py
index b5bbdeaf..e4221ad6 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -1,22 +1,18 @@
"""Public feature inventory for contract, prerequisite, and product smoke tests.
-The inventory is intentionally explicit. README-advertised behavior and exposed
-public surface area must have deterministic pytest contract coverage plus a
-product E2E scenario when that behavior is a user-facing product path. Liveness
-and route probes live in ``smoke/prereq`` and do not count as product coverage.
+The inventory is intentionally explicit. Public product behavior must have
+deterministic pytest contract coverage plus a product E2E scenario when that
+behavior is a user-facing product path. Liveness and route probes live in
+``smoke/prereq`` and do not count as product coverage.
"""
from dataclasses import dataclass
-from typing import Literal
-
-FeatureSource = Literal["readme", "public_surface"]
@dataclass(frozen=True, slots=True)
class FeatureCoverage:
feature_id: str
title: str
- source: FeatureSource
pytest_contract_tests: tuple[str, ...]
live_prereq_tests: tuple[str, ...]
product_e2e_tests: tuple[str, ...]
@@ -30,28 +26,10 @@ class FeatureCoverage:
return bool(self.pytest_contract_tests)
-README_FEATURES: tuple[str, ...] = (
- "zero_cost_provider_access",
- "drop_in_claude_code_replacement",
- "drop_in_codex_replacement",
- "pi_cli_integration",
- "provider_matrix",
- "per_model_mapping",
- "thinking_token_support",
- "heuristic_tool_parser",
- "discord_telegram_bot",
- "optional_authentication",
- "vscode_extension",
- "intellij_extension",
- "voice_notes",
-)
-
-
FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"zero_cost_provider_access",
"Configured provider accepts real conversation turns",
- "readme",
("tests/api/test_dependencies.py", "tests/providers/"),
("test_configured_provider_models_stream_successfully",),
("test_provider_text_multiturn_e2e",),
@@ -62,7 +40,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"drop_in_claude_code_replacement",
"Claude-compatible API, CLI, and editor protocol flows work",
- "readme",
("tests/api/test_api.py", "tests/cli/test_cli.py"),
("test_probe_and_models_routes", "test_claude_cli_prompt_when_available"),
(
@@ -86,7 +63,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"drop_in_codex_replacement",
"OpenAI Responses API and Codex CLI adapter route through the proxy",
- "readme",
(
"tests/api/test_openai_responses.py",
"tests/cli/test_entrypoints.py",
@@ -102,7 +78,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"pi_cli_integration",
"Pi discovers FCC models and sends Anthropic Messages through the proxy",
- "readme",
("tests/cli/test_entrypoints.py",),
("test_probe_and_models_routes",),
("test_pi_cli_prompt_e2e",),
@@ -113,7 +88,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"provider_matrix",
"Every configured provider prefix can satisfy conversation scenarios",
- "readme",
("tests/api/test_dependencies.py", "tests/providers/"),
("test_configured_provider_models_stream_successfully",),
("test_provider_matrix_presence_e2e", "test_provider_text_multiturn_e2e"),
@@ -124,7 +98,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"per_model_mapping",
"Fable, Opus, Sonnet, Haiku, and fallback mappings route explicitly",
- "readme",
("tests/application/test_routing.py", "tests/config/test_config.py"),
("test_model_mapping_configuration_is_consistent",),
("test_model_mapping_matrix_e2e",),
@@ -135,7 +108,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"mixed_provider_mapping",
"Model-specific overrides can route to different providers",
- "public_surface",
("tests/application/test_routing.py", "tests/config/test_config.py"),
("test_mixed_provider_model_mapping_when_configured",),
("test_model_mapping_matrix_e2e",),
@@ -146,7 +118,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"thinking_token_support",
"Thinking history, adaptive thinking, and redacted blocks are accepted",
- "readme",
(
"tests/contracts/test_stream_contracts.py",
"tests/providers/test_open_router.py",
@@ -166,7 +137,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"heuristic_tool_parser",
"Tool use and tool result continuation survive provider/client paths",
- "readme",
("tests/providers/test_parsers.py", "tests/contracts/test_stream_contracts.py"),
("test_live_tool_use_when_configured_model_supports_tools",),
(
@@ -183,7 +153,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"request_optimization",
"Local request optimizations return product responses without providers",
- "public_surface",
(
"tests/api/test_optimization_handlers.py",
"tests/api/test_routes_optimizations.py",
@@ -197,7 +166,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"smart_rate_limiting",
"Transient retries and disconnect cleanup preserve follow-up requests",
- "public_surface",
(
"tests/providers/test_provider_admission.py",
"tests/providers/test_nvidia_nim_degraded_retry.py",
@@ -211,7 +179,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"provider_hot_swap",
"Provider config changes preserve active streams while new requests switch",
- "public_surface",
(
"tests/runtime/test_provider_manager.py",
"tests/api/test_response_streams.py",
@@ -226,7 +193,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"discord_telegram_bot",
"Discord and Telegram product flows render progress and transcripts",
- "readme",
(
"tests/messaging/test_discord_platform.py",
"tests/messaging/test_telegram.py",
@@ -250,7 +216,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"subagent_control",
"Task-like tool output is rendered and controlled as foreground work",
- "public_surface",
("tests/providers/test_subagent_interception.py",),
(),
("test_messaging_subagent_control_e2e",),
@@ -261,7 +226,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"extensible_provider_platform_abcs",
"Provider and platform factories expose built-in extension points",
- "public_surface",
(
"tests/contracts/test_feature_manifest.py",
"tests/providers/test_provider_runtime.py",
@@ -275,7 +239,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"optional_authentication",
"Canonical bearer proxy authentication is enforced",
- "readme",
("tests/api/test_auth.py",),
("test_bearer_auth_is_the_only_supported_header_shape",),
("test_api_bearer_auth_contract_e2e",),
@@ -286,7 +249,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"vscode_extension",
"VS Code protocol-shaped requests work against the proxy",
- "readme",
(
"tests/core/anthropic/test_models.py::test_messages_request_accepts_adaptive_thinking_type",
),
@@ -299,7 +261,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"intellij_extension",
"JetBrains/ACP protocol-shaped requests work against the proxy",
- "readme",
(
"tests/core/anthropic/test_models.py::test_messages_request_accepts_adaptive_thinking_type",
),
@@ -312,7 +273,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"voice_notes",
"Voice note intake, cancellation, and transcription backends work",
- "readme",
(
"tests/messaging/test_voice_handlers.py",
"tests/messaging/test_transcription.py",
@@ -330,7 +290,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"anthropic_api_routes",
"Messages, count_tokens, errors, and stop use Anthropic-compatible shapes",
- "public_surface",
("tests/api/test_api.py",),
("test_probe_and_models_routes", "test_stop_endpoint_reports_no_messaging"),
(
@@ -346,7 +305,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"probe_routes",
"HEAD and OPTIONS compatibility probes are accepted",
- "public_surface",
("tests/api/test_api.py::test_probe_endpoints_return_204_with_allow_headers",),
("test_probe_and_models_routes",),
(),
@@ -358,7 +316,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"count_tokens_contract",
"Token counting accepts full Claude content payloads",
- "public_surface",
("tests/api/test_request_utils.py",),
("test_count_tokens_accepts_thinking_tools_and_results",),
("test_api_count_tokens_full_payload_e2e",),
@@ -369,7 +326,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"provider_proxy_timeout_config",
"Provider proxies and HTTP timeout settings reach provider config",
- "public_surface",
("tests/api/test_dependencies.py", "tests/providers/test_provider_runtime.py"),
(),
("test_proxy_timeout_config_e2e",),
@@ -380,7 +336,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"lmstudio_endpoint",
"LM Studio Messages and local no-key operation work when running",
- "public_surface",
("tests/providers/test_lmstudio.py",),
("test_lmstudio_models_endpoint_when_available",),
("test_lmstudio_messages_e2e",),
@@ -391,7 +346,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"llamacpp_endpoint",
"llama.cpp OpenAI Chat and local no-key operation work when running",
- "public_surface",
("tests/providers/test_llamacpp.py",),
("test_llamacpp_models_endpoint_when_available",),
("test_llamacpp_openai_chat_e2e",),
@@ -402,7 +356,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"ollama_endpoint",
"Ollama OpenAI Chat and local no-key operation work when running",
- "public_surface",
("tests/providers/test_ollama.py",),
("test_ollama_models_endpoint_when_available",),
("test_ollama_openai_chat_e2e",),
@@ -413,7 +366,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"package_cli_entrypoints",
"Installed package scripts report version and start the server",
- "public_surface",
("tests/cli/test_entrypoints.py", "tests/core/test_version.py"),
("test_fcc_server_entrypoint_starts_server",),
(
@@ -427,7 +379,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"claude_cli_drop_in",
"Claude CLI can send adaptive thinking and tool-shaped history",
- "public_surface",
("tests/cli/test_cli.py",),
("test_claude_cli_prompt_when_available",),
(
@@ -448,7 +399,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"messaging_commands",
"Messaging commands clear exact reply subtrees or whole managed chats",
- "public_surface",
(
"tests/messaging/test_handler.py",
"tests/messaging/test_handler_integration.py",
@@ -469,7 +419,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"tree_threading",
"Reply-based branches fork sessions and stay scoped",
- "public_surface",
(
"tests/messaging/test_tree_queue.py",
"tests/messaging/test_tree_concurrency.py",
@@ -489,7 +438,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"restart_restore",
"Persisted tree state restores reply routing after restart",
- "public_surface",
("tests/messaging/test_restart_reply_restore.py",),
(),
("test_restart_restore_and_session_persistence_e2e",),
@@ -500,7 +448,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"session_persistence",
"Session JSON preserves scoped trees and message logs",
- "public_surface",
("tests/messaging/test_session_store_edge_cases.py",),
(),
("test_restart_restore_and_session_persistence_e2e",),
@@ -511,7 +458,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"config_env_precedence",
"FCC_ENV_FILE, dotenv, and process env precedence are deterministic",
- "public_surface",
("tests/config/test_config.py",),
(),
("test_env_precedence_e2e",),
@@ -522,7 +468,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"removed_env_migration",
"Removed thinking env vars are ignored without changing defaults",
- "public_surface",
("tests/config/test_config.py",),
(),
("test_removed_env_migration_e2e",),
@@ -533,7 +478,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
FeatureCoverage(
"streaming_error_mapping",
"Canonical execution failures map to protocol-correct terminal output",
- "public_surface",
(
"tests/api/test_execution_failure_contract.py",
"tests/core/test_failure_protocol_mapping.py",
@@ -553,10 +497,6 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
)
-def feature_ids(*, source: FeatureSource | None = None) -> set[str]:
+def feature_ids() -> set[str]:
"""Return feature IDs covered by the inventory."""
- return {
- feature.feature_id
- for feature in FEATURE_INVENTORY
- if source is None or feature.source == source
- }
+ return {feature.feature_id for feature in FEATURE_INVENTORY}
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index fb0c84bd..5d4df81a 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -19,37 +19,7 @@ from free_claude_code.providers.openai_chat import (
)
from free_claude_code.providers.openai_codex import OpenAICodexProvider
from free_claude_code.providers.vertex import VertexProvider
-from smoke.features import FEATURE_INVENTORY, README_FEATURES, feature_ids
-
-VALID_SOURCE = {"readme", "public_surface"}
-
-
-def test_every_readme_feature_has_inventory_entry() -> None:
- missing = sorted(set(README_FEATURES) - feature_ids(source="readme"))
- extra_readme = sorted(feature_ids(source="readme") - set(README_FEATURES))
- assert not missing, f"README features missing inventory entries: {missing}"
- assert not extra_readme, (
- f"README inventory entries not in README_FEATURES: {extra_readme}"
- )
-
-
-def test_readme_provider_table_covers_full_catalog() -> None:
- repo_root = Path(__file__).resolve().parents[2]
- readme = (repo_root / "README.md").read_text(encoding="utf-8")
- provider_section = readme.split("## Choose A Provider", 1)[1].split("\n## ", 1)[0]
- rows = [line for line in provider_section.splitlines() if line.startswith("| [")]
-
- assert f"Switch among {len(PROVIDER_CATALOG)} cloud and local providers" in readme
- prefixes: list[str] = []
- for row in rows:
- example_cell = row.split("|")[3]
- match = re.search(r"`([a-z0-9_]+)/", example_cell)
- assert match is not None, row
- prefixes.append(match.group(1))
-
- assert len(rows) == len(PROVIDER_CATALOG)
- assert len(prefixes) == len(set(prefixes))
- assert set(prefixes) == set(PROVIDER_CATALOG)
+from smoke.features import FEATURE_INVENTORY
def test_feature_inventory_is_unique_and_decision_complete() -> None:
@@ -58,7 +28,6 @@ def test_feature_inventory_is_unique_and_decision_complete() -> None:
assert "claude_pick" not in ids
for feature in FEATURE_INVENTORY:
- assert feature.source in VALID_SOURCE, feature
assert feature.title.strip(), feature
assert feature.skip_policy.strip(), feature
assert feature.pytest_contract_tests, feature
@@ -92,7 +61,7 @@ def test_product_coverage_is_not_satisfied_by_prereq_probes() -> None:
assert all("_e2e" in name for name in feature.product_e2e_tests), feature
-def test_provider_and_platform_registries_include_advertised_builtins() -> None:
+def test_provider_and_platform_registries_include_builtins() -> None:
specialized_provider_classes = {
"openai": OpenAICodexProvider,
"nvidia_nim": NvidiaNimProvider,
diff --git a/tests/contracts/test_architecture_contracts.py b/tests/contracts/test_packaging_contracts.py
similarity index 62%
rename from tests/contracts/test_architecture_contracts.py
rename to tests/contracts/test_packaging_contracts.py
index 1d7d01f1..910fc4d2 100644
--- a/tests/contracts/test_architecture_contracts.py
+++ b/tests/contracts/test_packaging_contracts.py
@@ -1,30 +1,6 @@
import re
import tomllib
from pathlib import Path
-from urllib.parse import unquote, urlsplit
-
-
-def test_architecture_document_exists() -> None:
- repo_root = Path(__file__).resolve().parents[2]
-
- assert (repo_root / "ARCHITECTURE.md").is_file()
-
-
-def test_architecture_document_relative_links_resolve() -> None:
- repo_root = Path(__file__).resolve().parents[2]
- architecture = repo_root / "ARCHITECTURE.md"
- text = architecture.read_text(encoding="utf-8")
-
- missing: list[str] = []
- for match in re.finditer(r"(?<!!)\[[^\]]+\]\(([^)]+)\)", text):
- raw_target = match.group(1).strip()
- target = raw_target.split("#", 1)[0]
- if not target or urlsplit(target).scheme:
- continue
- if not (repo_root / unquote(target)).exists():
- missing.append(raw_target)
-
- assert missing == []
def test_root_env_example_is_the_single_template_source() -> None:
diff --git a/tests/contracts/test_smoke_tiers.py b/tests/contracts/test_smoke_tiers.py
index 801cf9d5..842b7f4f 100644
--- a/tests/contracts/test_smoke_tiers.py
+++ b/tests/contracts/test_smoke_tiers.py
@@ -9,15 +9,6 @@ from smoke.lib.report_summary import format_summary, summarize_reports
from smoke.lib.skips import skip_if_upstream_unavailable_events
-def test_smoke_readme_uses_env_gated_serial_commands() -> None:
- repo_root = Path(__file__).resolve().parents[2]
- text = (repo_root / "smoke" / "README.md").read_text(encoding="utf-8")
-
- assert "FCC_LIVE_SMOKE=1" in text
- assert "-n 0" in text
- assert "-m live" not in text
-
-
def test_smoke_report_summary_counts_regression_classes(tmp_path: Path) -> None:
report = {
"outcomes": [
diff --git a/tests/scripts/test_installers.py b/tests/scripts/test_installers.py
index 68944683..9766fd6a 100644
--- a/tests/scripts/test_installers.py
+++ b/tests/scripts/test_installers.py
@@ -1649,16 +1649,6 @@ def test_install_ps1_uses_x64_python_for_windows_arm_compatibility() -> None:
assert '$PythonRequest = "cpython-3.14.0-windows-x86_64-none"' in powershell
-def test_readme_install_section_has_no_manual_git_prerequisite() -> None:
- readme = (_repo_root() / "README.md").read_text(encoding="utf-8")
- install_section = readme.split("### 1. Install Or Update", 1)[1].split(
- "### 2. Start FCC", 1
- )[0]
-
- assert "Install Git" not in install_section
- assert "official native installers" not in install_section
-
-
@pytest.mark.parametrize("powershell", _powershells())
def test_install_ps1_rejects_invalid_download_before_execution(
powershell: str,
diff --git a/tests/scripts/test_uninstallers.py b/tests/scripts/test_uninstallers.py
index 48fe0df7..c15c8245 100644
--- a/tests/scripts/test_uninstallers.py
+++ b/tests/scripts/test_uninstallers.py
@@ -676,17 +676,3 @@ def test_uninstallers_guard_running_commands_and_preserve_shared_owners() -> Non
assert "is not installed" in text
assert "no tool" not in text
assert "nothing to uninstall" not in text
-
-
-def test_readme_uninstall_uses_raw_urls_and_verification_contract() -> None:
- text = (_repo_root() / "README.md").read_text(encoding="utf-8")
-
- assert (
- 'curl -fsSL "https://raw.githubusercontent.com/'
- 'Alishahryar1/free-claude-code/main/scripts/uninstall.sh" | sh'
- ) in text
- assert (
- '& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/'
- 'Alishahryar1/free-claude-code/main/scripts/uninstall.ps1")))'
- ) in text
- assert "verifies every FCC command is gone" in text