Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, 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)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / client-integration-harnesses

Client integration harnesses

Client integration harnesses connect supported native clients to the local gateway. They recognize an existing FCC connection, write only the client settings that FCC owns, refresh those settings when gateway state changes, and report safe status through the local admin surface. The supported set includes Claude clients, Codex, VS Code Chat, JetBrains ACP, and DSH Desktop. The integration-specific rules are collected in Client integration adapters.

Integration boundary

An integration harness is the boundary between FCC's gateway capabilities and a client that stores its own settings. The harness gives the client a local gateway URL, the required authentication data, and any client-specific model or launch information. It does not become the client: the native client still owns its user experience and local state.

Gateway connection contract

The gateway connection contract supplies a loopback proxy root URL and the configured proxy token. Claude clients receive shared Claude environment settings and model discovery. Codex receives the gateway's /v1 endpoint and a generated model catalog path. VS Code Chat receives FCC model entries that point to the gateway's Messages endpoint and carry the managed token as a request header. DSH Desktop receives an FCC provider definition, a default FCC model, and a credential reference for the local gateway. The shared URL helpers treat equivalent loopback names and trailing slashes as the same endpoint, so status does not fail only because a client stores localhost instead of 127.0.0.1.

References: src/…/server_urls.py• L8-55 src/…/claude.py• L11-24 src/…/codex.py• L35-50 src/…/vscode_chat_integration.py• L37-59 src/…/dsh_desktop_integration.py• L96-129

Capability projection

Each adapter projects gateway capabilities into the shape its client understands. Claude integrations use environment variables or gateway profile fields. Codex uses its Responses provider, a native authentication command, and a model catalog that reflects the provider models known to FCC. VS Code Chat uses the shared model catalog to publish model names, limits, input support, and reasoning support in its native model picker. DSH Desktop uses the shared model catalog to build its provider and default model entries. JetBrains ACP uses the installed Claude ACP command plus the same Claude gateway environment.

References: src/…/claude.py• L11-24 src/…/codex.py• L35-50 src/…/codex_model_catalog.py• L35-109 src/…/vscode_chat_integration.py• L8-59 src/…/dsh_desktop_integration.py• L96-103 src/…/jetbrains_acp_integration.py• L198-220

Integration lifecycle

The lifecycle has four actions: status inspects the client, connect establishes FCC-owned settings, disconnect removes those settings, and refresh updates an already recognized connection. Refresh is deliberately narrower than connect. It must not claim an unrelated or incomplete client configuration and must not select a user's model or provider for them.

Connection detection

Detection uses the client settings as evidence of ownership. The harness checks the gateway endpoint and the adapter's identifying fields before it reads or changes dependent state. An absent, changed, malformed, or externally owned configuration remains untouched unless the user explicitly asks for a connect or disconnect operation. DSH Desktop also requires its FCC provider, default model, and credential reference to match the current gateway state before it reports a connection.

References: src/…/claude_integration.py• L72-84 src/…/claude_desktop_integration.py• L272-288 src/…/codex_integration.py• L62-91 src/…/jetbrains_acp_integration.py• L79-92 src/…/vscode_chat_integration.py• L62-87 src/…/dsh_desktop_integration.py• L105-129

Configuration ownership

Connect and disconnect change only the FCC-owned part of a native configuration. User preferences, other providers, other Desktop profiles, unrelated agent entries, and other VS Code model groups remain outside the harness's ownership. DSH Desktop follows the same boundary by changing its FCC provider, FCC default selection, and FCC credential reference without replacing unrelated profile or credential data. Writes use replacement files so a failed update leaves the prior client configuration available for retry.

References: src/…/claude_integration.py• L86-112 src/…/codex_integration.py• L94-111 src/…/claude_desktop_integration.py• L291-300 src/…/vscode_chat_integration.py• L90-148 src/…/dsh_desktop_integration.py• L132-205 src/…/config_file.py• L9-33

Refresh coordination

Refresh runs during application startup and can also be requested from the local admin API. The runtime keeps one update record per integration and reports starting, ready, or failed with a change flag. A status request observes the task rather than repeating the file update. A repeated refresh is idempotent when the client already has the current gateway settings.

VS Code Chat and DSH Desktop follow the same rule when the model catalog changes. Catalog notifications mark each integration dirty, and one owned task drains that work until it has applied the latest catalog. A burst of catalog changes therefore coalesces into refresh work instead of starting one file update for every change.

This diagram shows how a provider catalog change reaches a connected client without configuring an unconnected client.

sequenceDiagram
    participant R as Application runtime
    participant H as Integration harness
    participant C as Native client settings
    participant G as Gateway catalog
    R->>H: Detect existing FCC connection
    alt Connection recognized
        R->>G: Wait for required gateway capability
        G-->>R: Current URL, token, or model catalog
        R->>H: Refresh owned settings
        H->>C: Write only changed FCC values
        C-->>H: Updated client state
    else No FCC connection
        H-->>R: No change
    end
    R-->>R: Publish integration status

References: src/…/integration_service.py• L40-58 src/…/integration_service.py• L83-194 src/…/integration_service.py• L288-333 src/…/dsh_desktop_integration.py• L208-224 src/…/application.py• L235-275 src/…/application.py• L444-471 src/…/application.py• L663-717

Gateway readiness

Codex, VS Code Chat, and DSH Desktop refresh and connect wait for a ready model catalog because the native clients must receive current model data. The runtime checks the catalog generation or revision again before writing. If the provider set changes during the wait, the operation starts again with the newer snapshot. Claude and JetBrains updates do not use that catalog wait because their connection contract does not require a generated model file.

References: src/…/integration_service.py• L210-317 src/…/integration_service.py• L346-392 src/…/integration_service.py• L687-720 src/…/application.py• L663-690 src/…/application.py• L692-717 src/…/paths.py• L80-83

Client integration families

FCC supports several client families with different native configuration models. The common lifecycle is stable across them, while each adapter owns path discovery, markers, resource checks, and cleanup rules.

ClientGateway connection formMain client-owned surface
Claude in VS CodeClaude environment settings and completed onboarding stateVS Code user settings and Claude state
VS Code ChatFCC model group with gateway Messages URLs and request headersVS Code Chat model group
Claude DesktopManaged gateway profile selected in the Desktop configuration libraryDesktop profile, selection metadata, and deployment mode
DSH DesktopFCC provider, default model, and credential reference in native YAML filesDSH Desktop profile and credentials
CodexFCC Responses provider and generated model catalogShared Codex TOML configuration
JetBrains ACPNamed Claude ACP agent with a discovered command and Claude environmentJetBrains ACP JSON configuration

For the path rules, ownership markers, resource checks, and adapter-specific startup behavior, see Client integration adapters.

Integration status

The local admin page exposes status and connect, refresh, and disconnect actions for each supported family. The API requires a loopback caller and a local origin. Responses are not cached because they describe current local files and in-progress update tasks.

References: src/…/admin_routes.py• L262-304 src/…/admin_routes.py• L307-395 src/…/admin_routes.py• L398-419 src/…/integration_service.py• L126-138 src/…/integration_service.py• L196-208 src/…/integration_service.py• L345-357 src/…/integration_service.py• L385-397 src/…/integration_service.py• L483-490

Launch preparation

Some integration adapters also prepare the command and environment that a native client uses to reach the gateway. Preparation returns a launch description rather than running a process. The caller owns process execution, while the harness owns client-specific command selection, environment cleanup, and private files needed by that process. Process ownership and managed child lifetimes are described in CLI launchers and managed processes.

Native command selection

JetBrains ACP resolves the installed ACP package and a compatible Node runtime before it writes the agent entry. It prefers the prior command when it remains valid and falls back to another supported installation. If the package, script, or runtime is not usable, the existing FCC entry stays intact and the user receives an actionable setup error.

References: src/…/jetbrains_acp_integration.py• L100-136 src/…/jetbrains_acp_integration.py• L139-195 src/…/jetbrains_acp_integration.py• L198-220

Child environment

Native clients receive a copy of the parent environment with conflicting provider settings removed or replaced. The environment keeps unrelated user state and adds loopback hosts to NO_PROXY, so local gateway traffic does not use an external proxy. This boundary prevents an old provider credential or proxy rule from silently taking precedence over the FCC connection.

References: src/…/environment.py• L10-35 src/…/environment.py• L46-69 src/…/claude.py• L27-42 src/…/codex.py• L63-93

Private launch resources

Generated files such as the Codex model catalog live in a private temporary directory owned by the launch scope. The directory and files use restrictive permissions and are removed when the scope closes. This keeps short-lived client inputs separate from durable user configuration and avoids overwriting a user file with generated data.

References: src/…/resources.py• L13-41 src/…/codex.py• L63-88 src/…/launch.py• L7-21

Runtime ownership

The application runtime is the single owner of integration operations. It serializes file changes with the configuration lock, runs blocking adapter work in an owned worker boundary, and drains update tasks during shutdown so a process does not close while a native configuration write is still active.

Update isolation

Each integration has its own update state and task. VS Code Chat and DSH Desktop add a dirty flag so catalog changes that arrive during a refresh are handled by the same worker. DSH Desktop also tracks explicit action revisions, so a connect or disconnect request cannot be silently replaced by a catalog-driven refresh. A failed refresh marks only that integration as failed, hides exception details from the admin response, and leaves other integrations available. A later refresh retries the same integration without making a status request perform a write.

References: src/…/integration_service.py• L40-81 src/…/integration_service.py• L100-194 src/…/integration_service.py• L232-317 src/…/integration_service.py• L328-397

Shutdown ownership

Startup schedules integration refreshes as owned tasks after configuration initialization. Shutdown cancels background integration work, waits for those tasks, and holds the configuration lock while it closes owned resources. This ordering prevents a late refresh from writing after the runtime has started to drain.

References: src/…/integration_service.py• L95-119 src/…/application.py• L235-283 src/…/application.py• L303-329 src/…/application.py• L1011-1046

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to a client connection marker must stay aligned across detection, refresh, status, connect, and disconnect. A marker that one action accepts and another action rejects can strand an FCC-owned configuration.
  • Changes to the gateway URL or token contract must update every client projection. Claude environment values, Desktop profile values, Codex /v1 settings, VS Code Chat request headers, JetBrains ACP environment values, and DSH Desktop provider credentials must continue to reach the same local gateway.
  • Changes to Codex, VS Code Chat, or DSH Desktop model discovery must preserve catalog readiness and generation or revision checks. A client must not receive a catalog from an older provider state.
  • Changes to an adapter's file writes must preserve unrelated native settings and atomic replacement. A partial update must remain safe to retry.
  • Changes to startup update tasks must preserve one task and one status record per integration. A status request must remain read-only while an update is in progress.
  • Changes to catalog notifications must preserve VS Code Chat and DSH Desktop dirty-drain behavior. A catalog update that arrives during a refresh must not be lost.
  • Changes to DSH Desktop action handling must preserve the action revision check. An explicit connect or disconnect must not be overwritten by a concurrent catalog refresh.
  • Changes to launch preparation must keep private generated resources alive until the child process no longer needs them and must keep local gateway hosts outside external proxy routing.
  • Changes to admin integration routes must preserve the loopback and local-origin boundary and the no-store response policy.

Important failure modes

TriggerConsequenceGuard
A client configuration no longer matches FCC's ownership marker or gateway URLRefresh reports no change and leaves the file aloneEach adapter recognizes its own complete connection before refresh
Codex, VS Code Chat, or DSH Desktop refresh starts before the model catalog is readyThe client can point at a missing or stale model catalog, provider, or model listThe runtime waits for catalog readiness and rechecks the generation or revision before writing
Native client settings are malformed or structurally invalidThe integration cannot be safely inspected or changedAdapters reject the document without rewriting it and return a safe admin error
A configuration write fails halfway through an updateThe client may otherwise lose its prior usable settingsAdapter writes use temporary files and replacement; retries reuse the durable source file
A provider catalog changes while VS Code Chat or DSH Desktop refreshesThe client can show a provider or model selection that does not match the current gateway stateThe service marks the integration dirty and drains another refresh with a stable snapshot
A DSH Desktop native file is absent or its home path is not usableFCC cannot create or update the DSH providerThe adapter checks the native package path and reports a setup error before configuration
JetBrains ACP has no compatible installed package or Node runtimeFCC cannot build a valid agent commandDiscovery validates registry metadata, package paths, and Node version before writing
Claude Desktop is managed by organization policyLocal FCC changes could conflict with enforced settingsThe Desktop adapter refuses managed installations
Claude Desktop disconnect cleanup stops partway throughFCC may remain selected or retain an owned profileA disconnect record makes cleanup retryable and blocks reconnect until removal finishes
One integration refresh raises an error during startupThat client stays stale while the whole application needlessly failsRuntime update state isolates the failure and keeps other integrations running
A refresh task writes while runtime shutdown closes configuration resourcesA late file update can race with process teardownThe runtime owns update tasks, serializes them with the configuration lock, and waits during shutdown

Key files

FileWhy to read it
src/…/integration_service.pyDefines integration actions, startup refresh, catalog-driven VS Code Chat and DSH Desktop updates, readiness checks, update state, and error boundaries.
src/…/application.pyConnects the service to runtime startup, admin actions, configuration locking, and shutdown.
src/…/admin_routes.pyDefines the local integration status and connect, refresh, and disconnect API surface.
src/…/ports.pyDefines the runtime capabilities exposed to the admin API without exposing adapter internals.
src/…/claude_integration.pyShows the Claude-in-VS-Code connection contract and ownership boundary.
src/…/claude_desktop_integration.pyShows the Desktop profile lifecycle, policy boundary, and retryable disconnect flow.
src/…/dsh_desktop_integration.pyShows DSH Desktop provider projection, native file ownership, catalog refresh, and credential cleanup.
src/…/codex_integration.pyShows Codex TOML recognition, catalog linkage, and non-destructive updates.
src/…/vscode_chat_integration.pyShows the VS Code Chat model group, catalog projection, and preservation of native model settings.
src/…/jetbrains_acp_integration.pyShows ACP agent ownership, installed-resource discovery, and command refresh.
src/…/claude.pyDefines shared Claude gateway settings used by integrations and launched sessions.
src/…/codex.pyDefines the Codex gateway provider settings and native launch preparation.
src/…/codex_model_catalog.pyDefines how gateway model metadata becomes a Codex client catalog.
src/…/model_catalog.pyDefines the shared model inventory and the client-facing model metadata used by VS Code Chat.
src/…/provider_manager.pyDefines provider generations, catalog readiness, revisions, and change publication.
src/…/environment.pyDefines child environment cleanup and local proxy bypass behavior.
src/…/resources.pyDefines private generated launch resources and their cleanup scope.
src/…/config_file.pyDefines atomic native configuration file replacement.
src/…/server_urls.pyDefines canonical local gateway URLs and equivalent URL recognition.
src/…/paths.pyDefines shared FCC paths for generated Codex catalog and Desktop disconnect state.