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 / cli-launchers-and-managed-processes

CLI launchers and managed processes

Free Claude Code (FCC) launchers connect supported coding clients to the local FCC proxy without changing the client's normal command use. They build a private child-process environment, provide client-specific model settings, and clean up the client process and temporary files. The same proxy owner can serve direct launches, the optional desktop shell, and managed Claude sessions. See CLI and desktop runtime for the wider runtime view and client integration adapters for the shared client boundary.

Launcher surface

The launcher surface provides one FCC command for each supported client. Each launcher keeps user arguments and adds only the connection, model, and safety settings that the client needs.

LauncherClient roleFCC connection style
fcc-claudeClaude CodeShared environment values
fcc-codexCodex CLIResponses provider settings and model data
fcc-piPi Coding AgentBundled provider extension
fcc-opencodeOpenCode CLIPrivate provider file and process overlay
fcc-agyAntigravity CLIPersistent native Gemini settings
fcc-clineCline CLIPrivate provider and model files
fcc-hermesHermes AgentInvocation-specific managed provider file
fcc-dshDeepSeek HarnessTemporary patch and provider settings
fcc-grokGrok BuildNative routing environment and command flags
fcc-museMuse CodeNative provider flags and routing environment
fcc-aiderAiderTemporary model settings and metadata

The clients use two main connection patterns. Some clients take routing data from environment values or command flags. Others need a client-native provider or model description before they can start. Antigravity is a separate persistent integration: it refreshes FCC-owned native model entries only after the user connects it. The launcher hides these differences from the user.

Launch lifecycle

The shared launch flow checks the client before it creates client settings. It then loads FCC settings, makes sure that a local proxy is healthy or starts its platform owner, prepares the child process, checks any private configuration that needs activation, and waits for the client to finish.

The diagram shows how a launcher turns a command into a checked and cleaned-up client process.

flowchart TD
    A[Launcher command] --> B[Find client]
    B --> C[Check client version when required]
    C --> D[Load FCC settings]
    D --> E[Check or start local proxy]
    E --> F[Fetch model catalog when required]
    F --> G[Build command and child environment]
    G --> H[Check private client settings when required]
    H --> I[Start client]
    I --> J[Wait and mirror exit result]
    J --> K[Remove process and temporary resources]

The proxy startup check uses a shared startup lock. If no FCC owner is ready, one launcher starts the platform owner and the other launchers wait for the same endpoint. A started FCC owner stays available after the client exits, so later launches can reuse it.

References: src/…/runner.py• L91-142 src/…/common.py• L271-355

Antigravity connection

The Antigravity launcher uses an explicit connection managed through the FCC Integrations page. A connected launch refreshes the FCC model catalog in Antigravity's native settings, preserves user-owned model entries, and records enough state to remove only FCC-owned entries later. The launcher stops before client startup when the connection is absent, and its --connect and --disconnect options direct the user to the same integration page.

References: src/…/agy.py• L31-61 src/…/agy.py• L77-94 src/…/antigravity_integration.py• L171-215 src/…/antigravity_integration.py• L242-279

Client checks

The launcher gives an install hint when the client binary is missing. A native version or capability check stops an incompatible client before FCC writes settings or starts work. The proxy health check is separate, so an installed client can still fail when the FCC owner cannot become ready.

The Cline launcher requires a recent enough client for its local provider and isolated Hub discovery path. Antigravity requires version 1.4.7 or newer before it refreshes its native connection.

References: src/…/common.py• L358-374 src/…/runner.py• L63-121 src/…/cline.py• L63-74 src/…/agy.py• L64-73

Launch plans

The shared runner gives each launcher the client path, FCC settings, proxy URL, auth token, inherited environment, and optional model catalog. A launcher returns the command and child environment. Some launchers also return a native check that confirms their private settings are active before the client starts normal work.

References: src/…/runner.py• L24-48 src/…/runner.py• L122-145 src/…/launch.py• L7-21 src/…/dsh.py• L74-105

Environment construction

FCC derives a child environment from the user's environment instead of replacing it. It removes values owned by the client or another provider, adds FCC routing and authentication values, and keeps local proxy addresses outside any configured network proxy.

Connection ownership

Environment ownership stops an old provider setting from silently taking priority over FCC. The shared policy removes selected keys or prefixes and then applies the FCC values. Some clients reject an existing process-level configuration because two configuration owners cannot safely merge.

Claude Code uses one connection policy for direct launches and other Claude client surfaces. The policy sets the proxy and auth values, enables model discovery, and disables unrelated update, feedback, and error-reporting paths.

References: src/…/environment.py• L10-43 src/…/environment.py• L46-69 src/…/claude.py• L11-39 src/…/grok.py• L55-98

Authentication handoff

The launcher loads the FCC proxy token once and passes it through the client contract. A client may receive it as an environment value, a temporary provider setting, or a command that prints the token for external setup. Launch errors remove the token from displayed messages.

Client-specific configuration keeps secret values out of files when the client supports an environment reference. Aider uses a launch-scoped environment name, while clients such as Cline and OpenCode place the token behind a private provider setting that exists only for that process.

References: src/…/runner.py• L91-116 src/…/runner.py• L146-155 src/…/aider_config.py• L14-39 src/…/cline_config.py• L45-67 src/…/opencode.py• L49-61

Model catalog projection

Catalog-aware launchers ask the authenticated local proxy for /v1/models before they start. FCC turns each valid result into a common model record with its wire name, provider reference, display name, capabilities, and token limits. The launcher then presents that record in the native shape required by its client.

The catalog request uses one of two client views:

  • messages for Messages-based clients such as Aider and Pi.
  • responses for Responses-based clients such as Cline, Codex, DeepSeek Harness, Grok Build, Hermes, Muse Code, and OpenCode.

An empty catalog, an invalid provider reference, or a default model that is not routable stops the launch. A model must include text support for the shared Python projection. Pi performs its projection inside its bundled extension because Pi loads that provider after the launcher starts.

Catalog acquisition

The local catalog is an authenticated snapshot of models that FCC can route at launch time. The shared Python path rejects malformed entries, duplicate wire names, missing provider references, and a missing or unroutable default. This keeps each client from starting with a model that the proxy cannot serve.

The Pi extension follows the same contract inside the Pi process. It validates the local URL and credentials, applies a request timeout, and turns the catalog into Pi model records with context and output limits.

References: src/…/catalog_http.py• L16-48 src/…/catalog_http.py• L51-138 src/…/pi_extension.ts• L69-143

Native client projections

Each client projection preserves the model facts that affect user choices and request safety. Aider receives model aliases and metadata for reasoning, images, context, and output limits. Cline receives a local Responses provider with streaming and tool support. OpenCode receives a process-local v2 provider and model view that allows only FCC routing, selects a default model, and reduces its compaction buffer when a model has a small context window.

DeepSeek Harness receives model profiles and a stream idle timeout derived from the FCC progress limit. Hermes uses an invocation-specific provider and applies model capability overrides to its main and auxiliary tasks. Antigravity receives native Gemini model entries with FCC-owned labels and capability data. These projections let different clients use the same FCC catalog without sharing one client configuration format.

References: src/…/aider_config.py• L26-83 src/…/cline_config.py• L28-123 src/…/dsh_config.py• L31-126 src/…/dsh.py• L74-105 src/…/hermes_config.py• L48-136 src/…/opencode_config.py• L25-112 src/…/pi_extension.ts• L145-192 src/…/agy.py• L31-61 src/…/antigravity_integration.py• L147-169

Temporary launch resources

Launchers that need client-native settings create private configuration resources for one client process. The resource scope creates a protected temporary directory only when a launcher needs it, writes each file without overwriting an existing path, and removes the directory when the launch ends.

These files carry provider settings, model metadata, patches, or catalogs that must not change the user's permanent client configuration. Antigravity is the exception: its explicit integration updates recognized FCC-owned entries in its persistent native settings and keeps a recovery record for disconnect. Secrets that a client needs at run time remain in the child environment or in a client-specific secret reference.

Private client state

Private state gives a launcher control of the client settings for one run without taking ownership of the user's normal setup. Cline places provider and model data in the private tree and redirects Hub discovery to that same tree. OpenCode uses a file and a process overlay. DeepSeek Harness receives a temporary settings and credentials path.

The process removes this state with the client process. A failed launch therefore does not leave an FCC provider selected in the user's normal client profile.

References: src/…/resources.py• L13-42 src/…/cline.py• L25-59 src/…/dsh_config.py• L31-83 src/…/dsh.py• L74-105 src/…/opencode_config.py• L59-87 src/…/agy.py• L31-61 src/…/antigravity_integration.py• L118-132

Desktop and server ownership

The desktop shell gives the same local FCC server a native tray or menu-bar control surface. Direct client launchers and the desktop shell coordinate through ownership locks so one configuration has one active server owner.

Desktop shell

The desktop shell is supported on Windows and macOS. Its tray adapter exposes Admin, server status, restart, and quit actions, while the server runs on an owned worker so the tray remains responsive. The entry point also supports exporting the application icon and marking a launch as an automatic owner start.

The desktop controller shows the tray before it claims desktop and server ownership. On exit it requests server shutdown, stops the tray, and waits for the server worker to finish. A second desktop launch can hand Admin to the existing FCC instance instead of starting another one.

References: src/…/desktop_entrypoint.py• L11-29 src/…/desktop_tray.py• L13-67 src/…/desktop.py• L48-115

Server owner lifecycle

The server supervisor owns one FCC runtime at a time. It claims the server owner lock, reports starting, running, stopping, or stopped state, and can replace a closed runtime when settings request a restart. A stop request prevents a later restart and runs final child-process cleanup for the server it owns.

When a launcher needs the proxy, the shared preflight starts fcc-desktop on Windows or macOS and fcc-server elsewhere with an automatic-start marker. It waits for a healthy endpoint and treats an existing manually started owner as the winner of a startup race. This lets clients share one server without taking ownership of its lifetime.

References: src/…/commands.py• L124-237 src/…/commands.py• L240-387 src/…/desktop.py• L117-162 src/…/common.py• L105-115 src/…/common.py• L226-355

Managed Claude sessions

Managed Claude sessions provide a long-lived conversation interface for message-driven flows. A session manager owns one session per conversation, while each task starts a Claude Code child that creates or resumes the session recorded for that conversation.

Session ownership

The manager tracks active sessions, sessions that are starting, and sessions that are closing. A new conversation first receives a temporary ID. When Claude Code returns its real session ID in streamed output, the manager links both IDs to the same session so later tasks can resume it and duplicate ownership stays rejected.

References: src/…/manager.py• L13-19 src/…/manager.py• L48-60 src/…/manager.py• L82-145

Task streaming

Each task runs Claude Code in stream-JSON mode with the FCC proxy environment and the configured workspace. The session reads stdout as events, extracts the first usable session ID, and forwards event objects to the messaging layer. Lines that are not JSON remain visible as raw events.

The task drains stderr while it reads stdout so a noisy child cannot block on a full pipe. It keeps only a bounded amount for reporting, separates known benign diagnostics from fatal text, and emits a final exit event after the child ends.

References: src/…/claude.py• L56-113 src/…/session.py• L64-89 src/…/session.py• L148-241 src/…/diagnostics.py• L25-40

Session shutdown

Cancellation and manager shutdown stop the active child instead of leaving it behind. The session marks itself closed, requests termination, and waits for the process. It uses a stronger kill only after the normal wait exceeds its limit. The manager removes ownership only after the stop succeeds.

References: src/…/session.py• L193-197 src/…/session.py• L262-297 src/…/manager.py• L147-199

Process registry coordination

The process registry is a safety net for FCC-owned child processes. Direct launchers register a child after creation and remove it after confirmed exit. Managed sessions use the same ownership idea so interruption or interpreter exit can still trigger best-effort cleanup.

Owned process cleanup

The registry tracks only FCC-owned process IDs. Windows can terminate a process tree through its platform tool. Other systems send a termination signal to the tracked process. This limits cleanup to processes started by FCC and avoids broad process termination.

The registry also installs an interpreter-exit hook once the first child is registered. The hook takes a snapshot of still-owned processes and attempts to stop each one. Normal session shutdown removes a process first, so the exit hook does not repeat work for a confirmed child.

References: src/…/process_registry.py• L1-6 src/…/process_registry.py• L21-76 src/…/common.py• L377-409 src/…/session.py• L134-147 src/…/session.py• L242-249

Change checklist

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

  • When adding a launcher, update its installed command, native argument and environment contract, catalog view, binary check, install hint, and resource lifetime.
  • When changing Antigravity integration, preserve explicit connection state, FCC-owned model markers, user-owned model entries, recovery data, and the native settings lock.
  • When changing OpenCode configuration, keep the v2 provider file, process overlay, FCC-only provider policy, default model, and context budget aligned.
  • When changing FCC proxy startup, keep the startup lock, owner locks, readiness probe, automatic-start marker, and platform command aligned.
  • When changing desktop lifecycle actions, keep tray state, server worker state, desktop singleton ownership, and Admin handoff aligned.
  • When changing the FCC model response, update the shared catalog projection and each native client projection. Include the Pi extension because it has its own projection.
  • When changing a client-owned environment key, update both its removal rule and its conflict guard so inherited settings cannot override FCC routing.
  • When changing managed Claude output or session IDs, keep the stream parser, temporary-to-real ID map, resume behavior, and shutdown ownership aligned.
  • When changing child startup or termination, preserve process registration until exit is confirmed and keep direct launchers and managed sessions on the same cleanup contract.

Important failure modes

TriggerConsequenceGuard
FCC proxy health check failsThe client does not start and reports how to start the platform owner.The preflight probes readiness, starts one owner under a lock, and waits within a fixed budget.
Two launchers start at the same timeBoth could try to bind the FCC port or create duplicate owners.The startup lock and server or desktop owner locks serialize ownership.
Client binary is missing or fails its compatibility checkThe launch exits with an install or version message.Binary lookup and native probes run before setup.
Antigravity is not connected or its native settings changed during an updateThe launch stops instead of routing through an unverified integration.The launcher checks connection state, uses a settings lock, and verifies the file before writing.
Authenticated model catalog is empty, malformed, or has an invalid defaultA catalog-aware client has no safe model route and the launch stops.The shared projection requires routable provider references and a valid default. Pi and Antigravity apply equivalent validation in their own projections.
Another process-level configuration is already setFCC could merge with another owner and route requests incorrectly.Clients such as Grok Build, Hermes, and OpenCode reject selected conflicts.
Private client settings do not activate or Cline discovers a user HubThe client can start with an unverified or wrong provider route.Launchers use native activation checks and Cline redirects discovery to its ephemeral tree.
Desktop server worker exits while the tray is activeTray actions can target a stopped server or leave the shell open.Restart starts a new owned worker, while quit stops the tray and joins the worker.
Managed child termination does not completeThe manager keeps ownership and reports a shutdown failure.Session stop waits, escalates after its limit, and removes ownership only after success.
Child emits fatal stderr or exits without a clean resultThe messaging flow receives an error and an exit event.Stderr is drained and classified with the final exit status.
A child survives an interrupted serverThe client process can remain active after FCC stops serving.The registry records only FCC-owned PIDs and attempts platform-specific cleanup at exit.

Key files

FileWhy to read it
pyproject.toml• L34-48Maps installed fcc-* commands to launcher entry points.
src/…/entrypoints.pyDefines lightweight server and diagnostic command entry points and version handling.
src/…/runner.pyDefines shared preflight, catalog loading, configuration, activation, startup, and error handling.
src/…/common.pyDefines proxy readiness and owner startup, binary lookup, child execution, and direct-launch process cleanup.
src/…/agy.pyDefines the Antigravity launcher, explicit connection requirement, native version gate, and child environment.
src/…/antigravity_integration.pyDefines persistent Antigravity model ownership, refresh, recovery state, and disconnect behavior.
src/…/opencode.pyDefines OpenCode v2 startup, process-local configuration, and environment ownership.
src/…/opencode_config.pyDefines the OpenCode provider, model projection, FCC-only policy, and context budget rules.
src/…/commands.pyDefines the FCC server supervisor, owner coordination, restart behavior, and Admin handoff.
src/…/desktop.pyCoordinates the desktop tray, server worker, singleton ownership, restart, and shutdown.
src/…/desktop_entrypoint.pyDefines supported desktop platforms, automatic startup, and icon export.
src/…/desktop_tray.pyDefines the native tray or menu-bar actions exposed to users.
src/…/environment.pyDefines child environment ownership and local proxy bypass behavior.
src/…/catalog_http.pyDefines the shared authenticated model catalog view.
src/…/aider_config.pyShows how FCC model facts become Aider settings and metadata.
src/…/cline.pyShows version checks and isolated Cline Hub discovery.
src/…/cline_config.pyDefines Cline's private provider and model view.
src/…/dsh.pyDefines the DeepSeek Harness launch path, argument handling, and FCC child environment.
src/…/dsh_config.pyDefines DeepSeek Harness model and timeout settings.
src/…/hermes_config.pyDefines the invocation-specific Hermes provider overlay.
src/…/resources.pyDefines lifetime and permission rules for private launch files.
src/…/process_registry.pyCoordinates best-effort cleanup for FCC-owned child processes.
src/…/manager.pyOwns the conversation-to-session pool and group shutdown.
src/…/session.pyOwns one managed Claude task's child process, stream, diagnostics, and stop path.
src/…/claude.pyDefines the managed Claude command, environment, and session-event contract.
src/…/pi_extension.tsShows the provider and model discovery path that runs inside Pi rather than in Python.