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-adapters

Client integration adapters

Client integration adapters connect native coding clients to the Free Claude Code gateway without taking ownership of unrelated client settings. They translate the gateway URL, managed token, model resources, and launch data into each client's native contract. This page covers the adapters for Antigravity, Claude, Claude Desktop, Codex, JetBrains ACP, and VS Code Chat. See Client integration harnesses for the wider integration service.

Adapter model

The adapters sit between the integration service and client-owned configuration. The service supplies the gateway connection and asks an adapter to inspect, create, repair, or remove that connection. Each adapter reports status in the terms of its client while limiting changes to FCC-owned values.

Connection lifecycle

Each adapter separates inspection, connection, disconnection, and refresh. Connection creates or updates the client link. Disconnection removes only that link. Refresh repairs a recognized link after a token, URL, installed client, or generated resource changes.

Refresh does not silently create a missing connection or change a user's selected model or profile. This boundary lets status expose incomplete client state without turning a repair action into an unexpected new connection.

The diagram shows how the service applies one gateway connection through a client-specific adapter.

flowchart LR
    A[Gateway URL and token] --> B[Integration service]
    B --> C{Client adapter}
    C --> D[Native client configuration]
    C --> E[Connection status]
    C --> F[Refresh or disconnect]
    D --> G[Client session]

References: src/…/application.py• L473-725 src/…/claude_integration.py• L115-167 src/…/codex_integration.py• L114-147

Shared contracts

The adapters use different file formats and client APIs, but they share the same ownership rules. They preserve unrelated settings, replace files safely, and report the native paths that an operator may need to inspect.

Configuration ownership

An adapter owns only the fields that identify the FCC connection. It merges those fields into an existing client document and removes them on disconnect. Other providers, profiles, model choices, comments where supported, and unrelated settings remain under client control.

The adapter rejects malformed or ambiguous configuration before it writes. It does not overwrite an unrelated entry that happens to use an FCC-reserved identity.

References: src/…/claude_integration.py• L39-69 src/…/claude_desktop_integration.py• L208-243 src/…/codex_integration.py• L47-60 src/…/jetbrains_acp_integration.py• L63-92

Refresh behavior

Refresh is a repair action for a recognized FCC connection. It can update credentials and other owned values, but it cannot select a provider, select a model, activate a profile, or create a missing client entry.

The application runs refresh under the same integration lock as connect and disconnect. Codex refresh also waits for the current model catalog before it writes the catalog reference.

References: src/…/application.py• L478-495 src/…/application.py• L663-717 src/…/claude_desktop_integration.py• L367-375 src/…/jetbrains_acp_integration.py• L223-227

Environment contract

Claude-based adapters use one environment contract. It points ANTHROPIC_BASE_URL to the local gateway, supplies ANTHROPIC_AUTH_TOKEN, enables gateway model discovery, and disables client traffic that could bypass the gateway.

Native launches remove conflicting Anthropic settings before they start. The child process keeps other user environment values. The adapter adds the gateway host and loopback hosts to NO_PROXY so local traffic does not pass through another proxy.

References: src/…/claude.py• L11-41 src/…/environment.py• L10-35 src/…/environment.py• L46-69

Antigravity adapter

The Antigravity adapter connects the Antigravity CLI to the gateway through its Gemini-provider settings. It generates the client’s custom model entries from the current FCC catalog while keeping the client’s other settings and model choices intact.

Configuration and launch surface

The native settings file is ~/…/settings.json. FCC keeps a private connection record at ~/…/antigravity-integration.json so it can identify and later remove only the models it generated. The record also stores the provider state that existed before FCC connected.

Connect and refresh set Antigravity's provider to Gemini and regenerate FCC model entries from the current catalog. Refresh requires an existing FCC connection. Disconnect removes only recognized FCC models and restores the prior provider when Antigravity still selects FCC.

The native launcher refreshes the connected model list before it starts agy. It passes GEMINI_API_KEY and GOOGLE_GEMINI_BASE_URL to the child process. A session launch selects the catalog's default model unless the command uses a native subcommand.

References: src/…/antigravity_integration.py• L26-31 src/…/antigravity_integration.py• L147-215 src/…/antigravity_integration.py• L217-279 src/…/agy.py• L31-61

Claude adapter

The Claude adapter configures the Claude Code extension used through standard VS Code settings. It connects the extension to the gateway through its environment settings and uses Claude Code's local state to complete first-run setup.

Configuration surface

The main file is the user's standard VS Code settings.json. Its platform-aware location comes from settings_path() in src/…/claude_integration.py. The companion state file is ~/.claude.json.

The adapter writes the shared Claude environment values and disables the login prompt. On connect it marks onboarding complete in .claude.json. On disconnect it removes only FCC environment entries and the login flag, then preserves the rest of both files.

References: src/…/claude_integration.py• L16-37 src/…/claude_integration.py• L86-112 src/…/application.py• L605-652

Connection recognition

Claude Code is connected when the login prompt is disabled, the gateway URL and token match, and gateway model discovery is enabled. The onboarding marker must also be true for the service to report a complete connection.

This split lets status find an incomplete first-run state without changing it. Connect completes the state. Disconnect does not erase the user's onboarding record.

References: src/…/claude_integration.py• L72-84 tests/…/test_claude_integration.py• L22-61

Native launch

The Claude launcher passes user command arguments through unchanged. It starts the native claude binary with the shared Claude environment and does not need a model catalog file.

The common launcher checks the local gateway before it starts the client. It loads the FCC token from application settings instead of trusting a token in the parent process.

References: src/…/claude.py• L12-34 src/…/runner.py• L91-145

Claude Desktop adapter

The Claude Desktop adapter manages FCC as a third-party Desktop profile. It lets users return to the native sign-in profile without losing other Desktop profiles or session data.

Profile surface

The Desktop root is platform-aware and normally ends in Claude-3p under the user's local configuration area. The adapter manages the FCC profile in configLibrary, its library metadata in configLibrary/_meta.json, and the deployment mode in claude_desktop_config.json.

The FCC profile uses a loopback HTTP or HTTPS gateway, a bearer token, model discovery, and an ownership header. The header lets the adapter distinguish its profile from another gateway profile with similar values.

References: src/…/claude_desktop_integration.py• L20-25 src/…/claude_desktop_integration.py• L40-50 src/…/claude_desktop_integration.py• L246-300

Policy and migration boundary

The adapter configures only unmanaged Desktop installations. It stops when an organization policy is present or cannot be read, because a local tool must not override administrator settings.

On Windows, it also waits when the old roaming Claude-3p root exists but the new local root does not. The user must start Desktop once so Desktop can migrate its data. FCC then retries without changing the old root.

References: src/…/claude_desktop_integration.py• L53-109 src/…/application.py• L575-595 tests/…/test_claude_desktop_integration.py• L19-50

Profile lifecycle

Connect creates or updates the FCC profile, registers it in the library, selects it, and switches Desktop to third-party mode. Disconnect records a retryable intent, returns selection to an empty Default profile when needed, switches back to first-party mode when appropriate, and removes the FCC profile.

A disconnect record at ~/…/claude-desktop-disconnect.json makes partial cleanup safe to retry. While it exists, refresh is blocked and a new connect must wait. The adapter preserves later user choices made during failed cleanup instead of applying an old selection over them.

References: src/…/claude_desktop_integration.py• L303-365 src/…/claude_desktop_integration.py• L378-418 src/…/paths.py• L80-87

Codex adapter

The Codex adapter connects native Codex clients through their shared TOML configuration. It adds FCC as the selected Responses provider while leaving the user's model choice and other provider entries intact.

TOML provider surface

The native file is config.toml under CODEX_HOME, or under ~/.codex when CODEX_HOME is not set. The FCC entry uses provider name fcc, the gateway's /v1 URL, the Responses wire API, and an auth command that asks the FCC CLI for the current proxy token.

Connect and disconnect change only FCC-owned provider fields. Disconnect removes the selected provider and catalog reference only when they still point to FCC, so a later choice of another provider is not undone.

References: src/…/codex_integration.py• L21-23 src/…/codex.py• L35-50 src/…/codex_integration.py• L123-147

Model catalog resource

Codex needs a model catalog that maps gateway models to Codex model records. The integration service waits for a ready catalog, then stores its absolute path as model_catalog_json in config.toml.

The shared catalog is ~/…/codex-model-catalog.json. A native Codex launch uses a private temporary catalog for one process lifetime, so private model data does not remain in the user's Codex configuration.

References: src/…/application.py• L663-712 src/…/paths.py• L80-83 src/…/codex.py• L63-93 src/…/resources.py• L13-41

Native launch

The Codex launcher prepares a model catalog, passes FCC provider settings as command-line TOML overrides, and starts the installed codex binary. It removes OpenAI and Codex connection variables from the child environment so an older provider cannot compete with FCC.

The --print-proxy-auth-token argument is a narrow credential handoff for Codex's auth command. It prints the managed token and does not start a Codex session.

References: src/…/codex.py• L18-47 src/…/codex.py• L17-31 src/…/codex.py• L63-93

JetBrains ACP adapter

The JetBrains ACP adapter registers Claude Code as a custom Agent Client Protocol server for JetBrains. It uses JetBrains' installed Claude ACP package instead of downloading or replacing that installation.

Agent configuration surface

The adapter writes ~/…/acp.json under agent_servers. Its owned entry is named Claude Code (FCC) and carries the Claude environment contract plus a private marker, FCC_JETBRAINS_ACP, that proves the entry belongs to FCC.

Other agent entries and fields on the FCC entry remain in place. Disconnect removes the FCC entry only when the marker identifies it as FCC-owned. An unrelated entry with the same display name is treated as a conflict.

References: src/…/jetbrains_acp_integration.py• L18-24 src/…/jetbrains_acp_integration.py• L32-34 src/…/jetbrains_acp_integration.py• L198-220 src/…/jetbrains_acp_integration.py• L230-242

Installed runtime resolution

Connect and refresh resolve the command from JetBrains' installed ACP registry and package files. The adapter verifies the installed package, its executable, its Node engine requirement, and a usable Node runtime before it changes acp.json.

The resulting agent command runs the installed claude-agent-acp script with --hide-claude-auth. The adapter prefers the prior installation when valid. It then searches other JetBrains installations and a system Node runtime.

References: src/…/jetbrains_acp_integration.py• L95-195 tests/…/test_jetbrains_acp_integration.py• L86-139

Refresh and launch boundary

Refresh updates an existing marked agent entry. It can rotate the gateway token or use a new installed ACP version, but it does not create the entry when absent. A missing or unusable installation fails without rewriting the connected entry.

JetBrains starts the configured ACP command as part of its own client flow. FCC supplies the command and environment. It does not own the JetBrains process lifetime.

References: src/…/jetbrains_acp_integration.py• L206-227 src/…/application.py• L483-534 tests/…/test_jetbrains_acp_integration.py• L173-199

VS Code Chat adapter

The VS Code Chat adapter connects VS Code Chat to the gateway through VS Code's user-level model provider file. It turns the current FCC model catalog into Chat model entries while keeping the rest of the user's VS Code configuration intact.

Provider configuration surface

The adapter writes chatLanguageModels.json beside the platform-aware VS Code user settings file. Its FCC group is a custom endpoint marked with an FCC-owned identity. Each catalog model becomes a Chat entry with the gateway /v1/messages endpoint and a request header containing the managed token.

Refresh replaces generated model details and keeps native group settings such as model preferences. It updates only an existing FCC group. Connect may create the group. Disconnect removes only the FCC-owned group, so a provider with the same display name but no FCC marker is not overwritten.

References: src/…/vscode_chat_integration.py• L29-59 src/…/vscode_chat_integration.py• L62-148 src/…/integration_service.py• L399-473

Native client launch

VS Code owns the Chat process and starts it through its normal extension flow. The adapter supplies the provider group and model resource data rather than managing the lifetime of VS Code itself. Catalog changes trigger an asynchronous refresh, but refresh does not create a missing group.

References: src/…/integration_service.py• L204-229 src/…/integration_service.py• L417-465

Change checklist

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

  • Keep connection recognition fields aligned with the values written by connect and refresh. A mismatch can make an existing client appear disconnected.
  • Keep the Claude environment contract aligned across Claude Code, JetBrains ACP, Claude Desktop, and native Claude launch paths.
  • Keep Antigravity's connection record and generated model ownership aligned with status, refresh, connect, and disconnect rules.
  • Keep VS Code Chat's group marker and generated model fields aligned with catalog refresh and disconnect behavior.
  • When Codex provider fields change, update persistent integration config, native launch overrides, and catalog readiness together.
  • Preserve the Desktop disconnect record contract when profile cleanup changes. A record that cannot be retried can strand the profile or block reconnect.
  • Keep platform path rules aligned with the paths reported in status results. Operators use those paths to repair client state.
  • Keep ACP package and Node-runtime checks aligned with the command written into acp.json. Otherwise refresh can leave a connected entry that JetBrains cannot start.

Important failure modes

TriggerConsequenceGuard
A client file is malformed or has the wrong shapeThe adapter rejects the action and leaves the file unchangedValidate the full owned document before writing
An unrelated entry uses an FCC-reserved identityConnect or disconnect could change another integrationRequire the FCC ownership marker before changing an existing entry
Claude Desktop is managed by an organizationLocal connect cannot safely change the Desktop profileDetect policy files or registry policy and return a managed-installation error
Windows Desktop data remains in the legacy roaming rootFCC cannot create an active root without risking native dataRequire Desktop's own migration before connect
Desktop disconnect stops part way throughThe profile may be removed while selection cleanup is incompleteRecord disconnect intent and retry until the FCC profile and record are gone
Codex's model catalog is not readyConnect or refresh can point Codex at stale or missing model dataWait for the current catalog generation before writing the config
The JetBrains ACP package or compatible Node runtime is missingConnect or refresh cannot produce a runnable agent commandVerify registry metadata, package boundaries, executable, and Node version first
Another process supplies conflicting provider environment valuesThe client can send traffic to the wrong serviceRemove owned conflicting variables and apply the canonical child environment

Key files

FileWhy to read it
src/…/application.pyShows how status, connect, disconnect, and refresh reach each adapter and how errors become service responses.
src/…/claude.pyDefines the shared Claude environment contract used by Claude Code and JetBrains ACP.
src/…/antigravity_integration.pyDefines Antigravity settings ownership, catalog models, refresh, and disconnect behavior.
src/…/agy.pyDefines the Antigravity native launch environment and catalog refresh boundary.
src/…/claude_integration.pyDefines the VS Code settings and Claude state-file contract.
src/…/claude_desktop_integration.pyDefines Desktop profile ownership, policy checks, migration boundaries, and retryable cleanup.
src/…/codex.pyDefines Codex provider values and native launch preparation.
src/…/codex_integration.pyDefines the persistent Codex TOML connection contract and catalog reference.
src/…/jetbrains_acp_integration.pyDefines ACP agent ownership, installed-runtime discovery, and the JetBrains launch command.
src/…/vscode_chat_integration.pyDefines VS Code Chat provider ownership, catalog model entries, refresh, and disconnect behavior.
src/…/environment.pyDefines child environment replacement and local proxy bypass behavior.
src/…/resources.pyDefines private launch resources and their cleanup lifetime.
src/…/runner.pyShows the common native launch sequence from settings and gateway checks to process start and cleanup.
src/…/paths.pyDefines FCC-owned paths for the Codex catalog, Desktop disconnect record, and launcher temporary files.