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.
| Launcher | Client role | FCC connection style |
|---|---|---|
fcc-claude | Claude Code | Shared environment values |
fcc-codex | Codex CLI | Responses provider settings and model data |
fcc-pi | Pi Coding Agent | Bundled provider extension |
fcc-opencode | OpenCode CLI | Private provider file and process overlay |
fcc-agy | Antigravity CLI | Persistent native Gemini settings |
fcc-cline | Cline CLI | Private provider and model files |
fcc-hermes | Hermes Agent | Invocation-specific managed provider file |
fcc-dsh | DeepSeek Harness | Temporary patch and provider settings |
fcc-grok | Grok Build | Native routing environment and command flags |
fcc-muse | Muse Code | Native provider flags and routing environment |
fcc-aider | Aider | Temporary 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:
messagesfor Messages-based clients such as Aider and Pi.responsesfor 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
| Trigger | Consequence | Guard |
|---|---|---|
| FCC proxy health check fails | The 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 time | Both 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 check | The 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 update | The 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 default | A 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 set | FCC 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 Hub | The 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 active | Tray 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 complete | The 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 result | The messaging flow receives an error and an exit event. | Stderr is drained and classified with the final exit status. |
| A child survives an interrupted server | The 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
| File | Why to read it |
|---|---|
| pyproject.toml• L34-48 | Maps installed fcc-* commands to launcher entry points. |
| src/…/entrypoints.py | Defines lightweight server and diagnostic command entry points and version handling. |
| src/…/runner.py | Defines shared preflight, catalog loading, configuration, activation, startup, and error handling. |
| src/…/common.py | Defines proxy readiness and owner startup, binary lookup, child execution, and direct-launch process cleanup. |
| src/…/agy.py | Defines the Antigravity launcher, explicit connection requirement, native version gate, and child environment. |
| src/…/antigravity_integration.py | Defines persistent Antigravity model ownership, refresh, recovery state, and disconnect behavior. |
| src/…/opencode.py | Defines OpenCode v2 startup, process-local configuration, and environment ownership. |
| src/…/opencode_config.py | Defines the OpenCode provider, model projection, FCC-only policy, and context budget rules. |
| src/…/commands.py | Defines the FCC server supervisor, owner coordination, restart behavior, and Admin handoff. |
| src/…/desktop.py | Coordinates the desktop tray, server worker, singleton ownership, restart, and shutdown. |
| src/…/desktop_entrypoint.py | Defines supported desktop platforms, automatic startup, and icon export. |
| src/…/desktop_tray.py | Defines the native tray or menu-bar actions exposed to users. |
| src/…/environment.py | Defines child environment ownership and local proxy bypass behavior. |
| src/…/catalog_http.py | Defines the shared authenticated model catalog view. |
| src/…/aider_config.py | Shows how FCC model facts become Aider settings and metadata. |
| src/…/cline.py | Shows version checks and isolated Cline Hub discovery. |
| src/…/cline_config.py | Defines Cline's private provider and model view. |
| src/…/dsh.py | Defines the DeepSeek Harness launch path, argument handling, and FCC child environment. |
| src/…/dsh_config.py | Defines DeepSeek Harness model and timeout settings. |
| src/…/hermes_config.py | Defines the invocation-specific Hermes provider overlay. |
| src/…/resources.py | Defines lifetime and permission rules for private launch files. |
| src/…/process_registry.py | Coordinates best-effort cleanup for FCC-owned child processes. |
| src/…/manager.py | Owns the conversation-to-session pool and group shutdown. |
| src/…/session.py | Owns one managed Claude task's child process, stream, diagnostics, and stop path. |
| src/…/claude.py | Defines the managed Claude command, environment, and session-event contract. |
| src/…/pi_extension.ts | Shows the provider and model discovery path that runs inside Pi rather than in Python. |