## Problem
OpenCode Zen uses the ambiguous `opencode/` identifier while OpenCode Go
uses `opencode_go/`. Renaming Zen without migrating saved configuration
would break existing installations.
## Changes
| Before | After |
| --- | --- |
| OpenCode Zen used `opencode/` in model mappings and `OPENCODE` in
diagnostics. | OpenCode Zen uses `opencode_zen/` and `OPENCODE_ZEN`
throughout FCC. |
| Existing FCC-owned environment files retained legacy Zen model
references. | Server startup rewrites legacy Zen model references before
settings validation. |
| Zen used `OPENCODE_PROXY` and `FCC_SMOKE_MODEL_OPENCODE`. | Zen uses
`OPENCODE_ZEN_PROXY` and `FCC_SMOKE_MODEL_OPENCODE_ZEN`. |
| The package version was `4.16.7`. | The package version is `4.16.8`. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This change renames the OpenCode Zen provider and related environment
settings, adds migration for legacy FCC-owned dotenv configuration on
the server path…
Preserve Claude feature flags in interactive clients (#1239)
## Problem
`fcc-claude` and the documented IDE setups forced `DISABLE_TELEMETRY=1`.
Claude Code disables feature-flag fetching with that variable, so
rollout features such as fullscreen rendering and mouse support fell
back to disabled defaults. Fixes #1238.
## Changes
| Before | After |
| --- | --- |
| Shared proxy policy forced telemetry off for interactive and managed
Claude sessions. | Interactive Claude sessions preserve the user's
telemetry choice, while managed headless tasks own the opt-out. |
| VS Code and JetBrains examples disabled Claude feature-flag fetching.
| Both IDE examples allow Claude to fetch rollout feature flags. |
| Environment contracts expected every Claude surface to disable
telemetry. | Regression tests distinguish interactive inheritance from
managed enforcement. |
| Package metadata reported version 4.12.0. | Package metadata and the
lockfile report version 4.12.1. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
…
Add a native FCC desktop launcher for Windows and macOS (#1225)
## Problem
Free Claude Code currently has to remain attached to a terminal, so
closing that window stops the proxy and users have no native way to
reopen Admin or control the background server. The contributed Windows
wrapper also would have introduced a second bundled server lifecycle
instead of reusing FCC's cleanup and restart ownership. Fixes #1147.
## Changes
| Before | After |
| --- | --- |
| Users keep `fcc-server` running in a terminal. | Windows and macOS
users can launch a console-free FCC Desktop host from a
desktop/application shortcut and control it from the tray or menu bar. |
| A wrapper would need to spawn and terminate a child server. | The
terminal and desktop paths share one in-process supervisor, one graceful
runtime shutdown path, and an OS-held singleton lock. |
| Installers manage only command entry points. | Windows installs
desktop and Start-menu shortcuts; macOS installs a per-user app bundle
and owned desktop link; uninstallers remove only those FCC artifa…
Remove obsolete init and server alias commands (#1220)
## Problem
FCC still publishes `fcc-init` and the `free-claude-code` server alias
from an obsolete installation flow. Configuration creation now belongs
to the Admin UI, while `fcc-server` owns startup and legacy migration.
## Changes
| Before | After |
| --- | --- |
| The package installs six console commands. | The package installs only
`fcc-server`, `fcc-claude`, `fcc-codex`, and `fcc-pi`. |
| `fcc-init` duplicates configuration creation outside the Admin UI. |
The Admin UI exclusively creates managed configuration, and server
startup retains legacy migration. |
| Smoke contracts and architecture describe the retired commands. |
Smoke contracts and architecture describe the supported command surface.
|
| Installer safety lists contain unexplained retired names. | Installer
safety lists document why retired names remain detectable during updates
and uninstall. |
| The package version is `4.11.4`. | The package version is `4.11.5`. |
<!-- greptile_comment -->
<details open><summa…
Keep FCC-local traffic off outbound proxies (#1214)
## Problem
FCC-local health and model-catalog requests inherited machine proxy
settings, so an outbound proxy could return HTTP 502 even while
`fcc-server` was healthy. Spawned agents inherited the same missing
loopback bypass. Fixes #1199.
## Changes
| Before | After |
| --- | --- |
| Launcher probes used the process-wide urllib proxy policy. | FCC-local
probes use one proxy-disabled transport owner. |
| Codex catalog loading could leave through an outbound proxy. | Codex
catalog loading uses the same direct local transport. |
| Claude, Codex, Pi, and managed messaging inherited incomplete bypass
lists. | Spawned clients preserve outbound proxies while merging FCC and
loopback hosts into `NO_PROXY` and `no_proxy`. |
| Local and upstream proxy responsibilities overlapped. | CLI-local
transport and provider-specific upstream proxies have explicit separate
owners. |
| Tests mocked launcher reachability without exercising proxy
interception. | A real fake-proxy regression proves loopba…
Make reasoning policy provider-neutral and client-aware (#1148)
## Problem
FCC reduced reasoning to global and route booleans, mixing client
intent, configuration, provider wire capabilities, output visibility,
and history replay. That discarded named client efforts, encouraged
model-name checks, and made provider behavior inconsistent.
## Changes
| Before | After |
| --- | --- |
| Admin exposed global and route thinking toggles. | Admin exposes
**Off**, **From client**, **Low**, **Medium**, **High**, **X-High**, and
**Max**; Fable, Opus, Sonnet, and Haiku also expose **Inherit**. |
| Request intent was repeatedly reduced to a boolean across routing and
providers. | The application boundary resolves one immutable
`ReasoningPolicy` with independent control, named effort, and exact
positive token budget. |
| Provider adapters could infer reasoning behavior from upstream model
names or versions. | Provider profiles translate only documented
provider-wide wire capabilities; architecture and contributor rules
prohibit model-specific reasoning branche…
Make version commands bypass server startup imports (#1135)
## Problem
`fcc-server --version` and `fcc-init --version` imported the complete
server composition root before printing package metadata, making
metadata-only commands take about 1.3 seconds and coupling them to
unrelated runtime dependencies.
## Changes
| Before | After |
| --- | --- |
| Installed entrypoints imported Uvicorn, the API, providers, and SDKs
before checking `--version`. | Lightweight entrypoints handle
`--version` before loading command implementations. |
| Server lifecycle and config initialization lived in the executable
adapter. | Heavy command behavior has one explicit owner in
`cli/commands.py`, while published script targets remain unchanged. |
| Version tests asserted output while the full runtime was already
imported. | Fresh-process regression tests prove both version paths
leave heavyweight runtime modules unloaded. |
| The median `uv run fcc-server --version` time was 1,286 ms. | The
measured median is 189 ms, about 6.8x faster. |
| Package version was 4.7…
Restore Claude model discovery without enabling telemetry (#1118)
## Problem
Claude Code's aggregate nonessential-traffic flag overrides gateway
discovery, so `fcc-claude` never requests `/v1/models` and `/model`
omits FCC models. Deleting the flag alone also re-enables updater,
feedback, error-reporting, and telemetry traffic. Fixes #1112.
## Changes
| Before | After |
| --- | --- |
| FCC forced the aggregate traffic flag, which suppressed gateway model
discovery. | The shared Claude environment removes inherited aggregate
flags and enables gateway discovery. |
| Removing the aggregate flag would restore every optional traffic
category. | Four granular opt-outs preserve the existing updater,
feedback, error-reporting, and telemetry policy. |
| VS Code and JetBrains examples documented the discovery-blocking flag.
| Both IDE examples use the same granular environment policy as
`fcc-claude`. |
| The retry smoke counted locally short-circuited auxiliary requests as
provider retries. | The retry smoke counts terminal failures and still
requires exact…
Make proxy authentication bearer-only across every client (#1096)
## Problem
Proxy authentication selected the first of three credential headers, so
a stale `X-API-Key` could mask valid bearer authorization and leave
Claude CLI or IDE clients at their login gate. Fixes #902.
## Changes
| Before | After |
| --- | --- |
| FCC accepted three proxy credential headers and stripped legacy model
suffixes. | FCC accepts one exact `Authorization: Bearer` token without
mutation. |
| Conflicting provider credentials could override valid proxy
authorization. | Unrelated credential headers are ignored during proxy
authentication. |
| Codex catalog discovery and Pi catalog or inference paths used API-key
authentication. | Every FCC-owned Codex and Pi path uses bearer
authorization. |
| Authentication failures referred ambiguously to an API key. |
Authentication failures identify the proxy authentication token. |
| FCC reported version `4.2.0`. | FCC reports version `4.3.0`. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>…
Expose the Admin startup browser preference (#1091)
## Problem
The Admin startup browser preference bypassed FCC's settings system.
Managed configuration could not control it, and the Admin UI did not
expose it.
## Changes
| Before | After |
| --- | --- |
| The launcher read `FCC_OPEN_BROWSER` directly from the process
environment. | The launcher reads the typed `open_admin_browser`
setting. |
| The startup browser preference was absent from the Admin UI. | Runtime
settings expose an **Open Admin on Startup** toggle. |
| Managed configuration could not disable browser launch. | Admin
changes persist for the next server launch without restarting the
running proxy. |
| Browser launch defaulted on through launcher fallback logic. | Browser
launch defaults on through the canonical Settings and template contract.
|
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR exposes the Admin startup browser preference through the normal
settings flow. The main changes are:
- Added `FCC_OPEN_BROWSER` as…
## Problem
Pi registered FCC models but rejected the launcher scope because nested
provider/model IDs contain an additional slash. Pi then retained a
non-FCC model, so prompts did not reach the local proxy.
## Changes
| Before | After |
| --- | --- |
| `free-claude-code/*` matched only one model-ID path segment. |
`free-claude-code/**` matches every nested FCC provider/model ID. |
| The integration architecture described a single-segment scope. | The
integration architecture records the nested routing-reference contract.
|
| The package version remained 3.6.0. | The package version is released
as 4.0.0. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR updates Pi launcher routing so nested FCC model IDs can be
scoped. The main changes are:
- Pi sessions now pass `free-claude-code/**` as the model scope.
- Pi launcher tests now expect the recursive scope string.
- Architecture docs now describe nested FCC provider/model routing.
- Pack…
## Problem
FCC had no first-class Pi path, so Pi users had to maintain provider
configuration themselves. FCC's installers and ownership docs also
covered only Claude Code and Codex.
## Changes
| Before | After |
| --- | --- |
| Pi required persistent user-managed provider configuration. | `fcc-pi`
registers an ephemeral FCC provider from the live model catalog and
leaves Pi-owned state untouched. |
| Client launchers normalized blank proxy authentication separately. |
Claude, Codex, and Pi share one neutral proxy-auth policy. |
| FCC installers and uninstallers did not account for Pi. | Installers
delegate missing Pi setup to its official platform installer, while
uninstallers remove only `fcc-pi` and preserve native Pi. |
| Pi compatibility had no executable FCC contract. | Deterministic
launcher and lifecycle coverage plus a real Pi 0.80.6 smoke verify model
discovery and `/v1/messages` end to end. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></su…
Disable nonessential Anthropic traffic for FCC Claude sessions (#1083)
## Problem
Claude proxy environment policy was duplicated between `fcc-claude`,
managed messaging, and live smoke drivers. Managed messaging preserved a
legacy endpoint variable, inherited more Anthropic state, and did not
disable nonessential traffic, so FCC-launched Claude sessions could
drift apart.
## Changes
| Before | After |
| --- | --- |
| `fcc-claude` and managed messaging assembled proxy environments
independently. | One shared owner strips inherited Anthropic variables
and configures proxy URL, auth, discovery, compaction, and
nonessential-traffic policy. |
| Managed messaging carried a `/v1` API URL and converted it back to a
proxy root while also setting a legacy endpoint variable. | Managed
messaging receives the loopback-safe proxy root and uses the supported
`ANTHROPIC_BASE_URL` contract directly. |
| Managed and interactive policy could diverge while smoke drivers
duplicated both shapes. | `fcc-claude`, messaging, and Claude smoke
drivers use the same canonical envi…
Make application shutdown completion-driven (#1056)
## Problem\n\nShutdown could report success after bounded messaging
cleanup, hidden persistence failures, or failed managed-process stops.
An Admin restart could then construct a replacement while the old
runtime still owned work.\n\n## Changes\n\n| Before | After |\n| --- |
--- |\n| Runtime reused bounded interactive stop semantics for terminal
messaging cleanup. | Workflow close cancels work, stops managed
sessions, awaits every claim and recovery task, then flushes
persistence. |\n| Explicit persistence failures were logged and treated
as successful writes. | Explicit flushes and authoritative writes
propagate failure and stay dirty for retry; timer writes remain best
effort. |\n| Managed sessions and aliases were removed before subprocess
termination was confirmed. | Manager and session terminal states prevent
reuse, retain failed owners and PIDs, reject ID collisions, and retry
exact sessions. |\n| Admin restart followed the restart request even
after incomplete shutdown. | Superv…
Isolate nested Codex launches from parent task context (#1055)
## Problem\n\nNested Codex launches inherited the parent task's thread,
shell, permission, and origin identity. This could attach a new client
or compatibility probe to the parent task, hang startup, or decode probe
output with the wrong Windows locale.\n\n## Changes\n\n| Before | After
|\n| --- | --- |\n| cc-codex forwarded parent-only Codex task context. |
cc-codex removes parent-only task context while preserving user
configuration such as CODEX_HOME. |\n| The installed-Codex probe
inherited the parent task and user Codex home. | The probe runs with a
standalone task identity and isolated Codex home. |\n| The probe decoded
output with the platform default encoding. | The probe decodes output as
UTF-8 with safe replacement. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR isolates nested Codex launches from parent task identity. The
main changes are:
- Strips Codex thread, shell, permission, and origin context from
launched child envi…
Use installed metadata as the single package version source (#1051)
## Problem
FCC runtime surfaces reported stale, unrelated versions, and users could
not inspect the installed FCC version without starting the server or
scaffolding configuration.
## Changes
| Before | After |
| --- | --- |
| FastAPI/OpenAPI and the web-tools user agent duplicated stale release
literals. | Every FCC runtime surface reads installed distribution
metadata through one `core.version` owner. |
| FCC-owned commands had no side-effect-free version query. |
`fcc-server`, `free-claude-code`, and `fcc-init` print the installed
version whenever `--version` is present, before any configuration or
process work. |
| Wrapped Claude and Codex argument handling was adjacent to FCC command
behavior. | Claude and Codex launchers remain transparent and pass
`--version` to their wrapped clients unchanged. |
| A source-only checkout had no explicit fallback contract. | Missing
distribution metadata reports `0+unknown`, while malformed installed
metadata still fails visibly. |
| Version be…
Establish single-owner runtime with stream-safe provider hot swaps (#1036)
## Problem
Provider runtime ownership was split between lifecycle code and mutable
FastAPI state, so Admin replacements could leak the new runtime,
double-close the old runtime, or close providers still serving active
streams. The API package also owned concrete process composition,
obscuring subsystem boundaries.
## Changes
| Before | After |
| --- | --- |
| FastAPI routes inspected several concrete `app.state` resources. |
FastAPI receives one explicit `ApiServices` boundary and stores only
`app.state.services`. |
| Admin Apply persisted config and directly replaced one runtime
reference. | Admin Apply validates a candidate, commits atomically, and
publishes it through the single runtime owner. |
| Provider replacement could close clients used by active streams. |
Generation leases retain old providers until each streaming or
non-streaming response finishes. |
| Provider generations owned discovery state and model metadata. |
`ProviderRuntimeManager` owns one application-lifetime …
Move runtime packages under src namespace (#1029)
## Problem
Runtime modules were published as generic top-level packages like `api`,
`cli`, and `providers`. That shape is fragile for PyPI packaging and
weakens explicit ownership boundaries.
## Changes
| Before | After |
| --- | --- |
| Runtime code lived in root-level packages. | Runtime code lives under
`src/free_claude_code/`. |
| Console scripts targeted top-level modules. | Console scripts target
namespaced modules. |
| Tests and smoke helpers imported old package roots. | Tests and smoke
helpers import `free_claude_code.*`. |
| Packaging listed six root packages. | Packaging builds the single
namespaced package. |
| Contracts allowed old root package directories. | Contracts require
the src namespace and reject old root imports. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR moves the runtime packages into the `src/free_claude_code`
namespace. The main changes are:
- Console scripts now point to `free_claude_code.*` entrypoi…
## Problem
FCC did not expose Hugging Face Inference Providers as a selectable
backend. Voice transcription also used the legacy `HF_TOKEN` setting
instead of the canonical Hugging Face API key.
## Changes
| Before | After |
| --- | --- |
| Hugging Face models could not be selected through provider-prefixed
routing. | Hugging Face routes through a thin OpenAI-chat provider using
`huggingface/<model>`. |
| Provider credentials did not include `HUGGINGFACE_API_KEY`. | Admin
config, settings, smoke config, and docs use `HUGGINGFACE_API_KEY`. |
| `HF_TOKEN` remained a voice-only config key. | Owned dotenv files
migrate `HF_TOKEN` to `HUGGINGFACE_API_KEY`, while explicit
`FCC_ENV_FILE` users get a warning. |
| Version metadata stayed on `2.6.0`. | Version metadata moves to
`3.0.0` with a refreshed lockfile. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR adds Hugging Face Inference Providers as a selectable backend.
The main changes are:
…
Refactor admin config into catalog-driven package (#926)
## Problem
Admin config was a single responsibility hub with manually duplicated
provider metadata. Provider labels, fields, template loading,
validation, persistence, and status lived in one place.
## Changes
| Before | After |
| --- | --- |
| Admin config lived in one large `api/admin_config.py` module. | Admin
config lives in package modules for manifest, sources, values,
validation, persistence, and status. |
| Provider admin fields and UI labels were manually duplicated. |
Provider admin fields and display names derive from `PROVIDER_CATALOG`
with admin-only help overrides. |
| `fcc-init` and Admin UI loaded `.env.example` separately. | `fcc-init`
and Admin UI use shared `config.env_template` loading. |
| Architecture docs pointed to the old admin config module. |
Architecture docs describe the package owners and catalog-driven
provider manifest. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR refactors admin configuration into …
Refactor CLI surfaces around launchers and managed Claude (#861)
## Problem
The CLI package preserved a generic adapter layer and managed Codex
parser path that did not match the supported customer workflows.
Messaging runs Claude Code sessions, while Codex is supported through
`fcc-codex` and extensions.
## Changes
| Before | After |
| --- | --- |
| `fcc-claude` and `fcc-codex` shared generic adapter plumbing. |
`fcc-claude` and `fcc-codex` use explicit launcher modules. |
| Messaging depended on a generic CLI session abstraction. | Messaging
depends on managed Claude Code sessions. |
| Codex catalog generation lived as a top-level CLI helper. | Codex
catalog generation lives under the Codex launcher owner. |
| Tests asserted deleted internal adapter shapes. | Tests assert
launcher, managed-Claude, and customer-surface behavior. |
## Summary
- split the admin UI into Providers, Model Config, and Messaging views
- remove generated env, diagnostics, smoke, managed-label, and fixed
cloud/runtime settings from the visible admin UX
- make Z.ai base URL, Claude workspace, and Claude CLI binary fixed
app-level behavior instead of managed env fields
## Verification
- uv run ruff format
- uv run ruff check
- uv run ty check
- uv run pytest