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-and-desktop-runtime

CLI and desktop runtime

Free Claude Code provides command-line and desktop entrypoints that connect interactive coding clients to one local FCC server. The runtime prepares a safe local connection, starts or supervises the server when needed, reports local diagnostics, and cleans up client processes when a session ends.

Runtime entrypoints

The installed commands separate server ownership from client ownership. fcc-server starts the local HTTP service, fcc-doctor reports local diagnostics or disconnects recognized integrations, the fcc-* commands prepare a native coding client, and fcc-desktop provides a tray or menu-bar host for the same server.

The server is the shared boundary for local administration and provider access. Client commands do not create a second server; they check the existing local service and then pass the user's command and working context to the selected native client. The API gateway describes the service boundary that these entrypoints use.

Command entrypoints

The command entrypoints keep startup light and defer full server assembly until the user asks to run the server. The server and diagnostic commands support a version query without loading the application, which keeps metadata checks independent from runtime setup. The server command also turns off console logging when a desktop owner starts it in the background. The installed command map is defined in pyproject.toml.

References: src/…/entrypoints.py• L1-35 pyproject.toml• L46-63

Diagnostic reports

The diagnostic command creates a shareable JSON report from the local runtime and writes it to standard output. It also tries to copy the same report to the desktop clipboard, but clipboard support is optional, so a clipboard failure leaves the report available for manual copying.

This gives support and bug reports a low-friction view of local state without changing the server or client lifecycle. The command reports its clipboard result separately from the JSON so the report remains useful in terminal-only environments.

References: src/…/doctor.py• L1-44 src/…/clipboard.py• L1-14 src/…/entrypoints.py• L29-35

Integration disconnect

The diagnostic command can also disconnect recognized local editor and desktop integrations before FCC is uninstalled. This path reuses each integration's connection owner without starting the server or contacting providers, so installed tools and recovery data remain available if a disconnect fails.

The cleanup runs each operation in a retry-safe order. It reads only the connection settings needed to remove FCC's local links, reports a clear failure for unreadable settings or blocked app files, and leaves earlier successful changes in place for a later retry.

References: src/…/doctor.py• L18-35 src/…/integration_cleanup.py• L27-35 src/…/integration_cleanup.py• L67-148

Local HTTP service

The local HTTP service owns the application runtime and exposes the local proxy and Admin UI. A server supervisor loads settings, builds the application, runs the HTTP server, and reports a small lifecycle state so the desktop shell and other callers can show whether the service is starting, running, stopping, or stopped.

The supervisor treats a settings-driven restart as a full runtime replacement. It waits for the current application to close before starting the next generation. On normal or interrupted shutdown it also asks tracked child processes to stop, so the server does not leave client work behind.

The HTTP adapter ties server state to startup and shutdown callbacks. It also routes server logs through FCC's logging path and masks API keys in access-log query strings. This keeps short-lived startup exits and normal shutdowns inside the same runtime cleanup path without exposing credentials in local logs.

The local service uses an ownership lock to distinguish a running FCC instance from an unrelated process when the configured port is busy. If another FCC instance owns the configuration, a new server does not compete for the port. Desktop and other short-lived callers can wait for that instance to become ready and hand the user to its Admin UI instead.

The local service can open the Admin UI after its health endpoint responds. Browser handoff runs independently of the server's main work and is allowed only while the same server generation remains ready. This avoids sending the browser to a port that has not started yet or handing it to a runtime that is already stopping.

References: src/…/commands.py• L38-68 src/…/commands.py• L71-121 src/…/commands.py• L124-239 src/…/commands.py• L240-387 src/…/commands.py• L393-460 src/…/uvicorn_server.py• L14-85 src/…/bootstrap.py• L45-104

Desktop runtime

The desktop runtime turns the local server into a background application with a native status-area control. It keeps the tray loop responsive while the server runs in its own worker, and it gives the user direct actions for opening Admin, checking status, restarting the server, and quitting.

Desktop singleton

The desktop host allows only one FCC desktop instance for a user configuration directory. A second launch does not start another server; it waits for the existing local service and opens the current Admin UI instead. This keeps one local server responsible for shared state and avoids competing tray controls.

An auto-started desktop owner uses the same ownership rules for background startup. If a desktop instance already owns the configuration, the new owner exits instead of opening a second user-facing tray or taking over the existing runtime.

References: src/…/desktop.py• L117-162 src/…/interprocess_lock.py• L41-82

Desktop lifecycle

The desktop controller shows the tray and starts the server during tray setup. When the tray exits, it requests a server stop and waits for the server worker to finish. Restart uses the active supervisor when possible, or starts a new server worker if the prior worker has already ended.

The platform adapter supplies the native UI but does not own server policy. The current adapter supports Windows and macOS; other platforms reject the desktop launch while the command-line server and client entrypoints remain available. The tray exposes Admin, status, restart, and quit actions. The desktop entrypoint can export the application icon for packaging without starting the tray runtime, and macOS can install its app shell through a separate command-line option. Installation errors are reported as a failed command instead of starting the tray.

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

Interactive client launches

An interactive client launch is a short preparation flow around the local proxy. The shared launcher path finds the native binary, checks compatibility, reuses or starts the proxy, gets model data when the client needs it, creates temporary private resources, and then starts the native process with the user's arguments.

If the proxy is not ready, concurrent launchers coordinate through a startup lock. One launcher starts the platform server owner and the others wait for the same health result. The owner stays alive after the interactive client exits, so later commands can reuse the local runtime.

The launcher keeps the native client's command meaning intact. FCC supplies the connection and runtime context; the client remains responsible for its own interactive prompts, display, and command behavior. Launcher-specific settings, resource files, and process rules belong in CLI launchers and managed processes.

Launch preparation

The preparation sequence fails early when the native binary is missing, the client is too old, the local proxy cannot answer its health check or cannot be started, authentication is unavailable, or a required model catalog is empty. Some clients also run a post-configuration check before the process starts. OpenCode requires a stable version 2 release and always runs in FCC-managed standalone mode. Antigravity CLI requires version 1.5.9 or newer and receives FCC settings only for the launched process. User-facing errors identify the failed stage and avoid exposing the proxy token.

The launch scope owns temporary files for the lifetime of the native process. These files support clients that need private configuration without changing a user's permanent client settings. The scope removes them when the process exits.

DeepSeek Harness follows this shared launch path for normal interactive commands. It passes a temporary FCC patch and an FCC-owned child environment to the client, while simple inspection commands such as version and help can pass through without starting the FCC setup.

References: src/…/runner.py• L24-48 src/…/runner.py• L91-152 src/…/common.py• L226-355 src/…/common.py• L358-409 src/…/resources.py• L13-42 src/…/opencode.py• L65-79 src/…/agy.py• L26-65 src/…/dsh.py• L44-67 src/…/dsh.py• L74-105 src/…/dsh.py• L122-146

Client model catalogs

Each launcher maps the shared FCC model catalog into the native client's own provider format. This keeps model names and key capabilities such as reasoning, image input, context size, and output limits visible in the interactive client without requiring permanent edits to the user's client configuration.

The launch adapters use several broad patterns. File-based adapters create private provider settings for clients such as Aider, Cline, and Hermes. OpenCode receives process-local provider data that names FCC, selects the default model, exposes model limits, and restricts provider use to FCC. Its runtime budget also adapts to the smallest known context window. Antigravity receives a temporary settings file with FCC-owned Gemini model entries and retires any recognized older FCC connection before launch. DeepSeek Harness receives a temporary patch that selects FCC as its provider, sets the default model, and disables its direct provider and web-tool paths. Extension-based adapters let Pi fetch and validate the local catalog at startup, while the Codex catalog writer projects the same model data into the format used by Codex. The Codex app-server integration describes the Codex-specific path.

References: src/…/aider_config.py• L15-60 src/…/cline_config.py• L18-85 src/…/hermes_config.py• L36-108 src/…/opencode.py• L35-62 src/…/opencode_config.py• L25-112 src/…/agy.py• L26-61 src/…/antigravity.py• L132-201 src/…/dsh.py• L74-105 src/…/dsh_config.py• L31-94 src/…/pi_extension.ts• L70-154 src/…/codex_model_catalog.py• L35-65

Client environment

Each client receives a child-process environment that routes its FCC-owned traffic to the local proxy while preserving unrelated user state. The shared policy removes conflicting connection settings only where the launcher owns them, applies client updates, and adds local destinations to NO_PROXY so loopback traffic does not pass through a machine-wide proxy.

The Claude client uses the same policy for both interactive launches and managed sessions. It sets the local base URL and authentication token, enables the needed gateway discovery, and disables client behaviors that would send control traffic outside the local runtime. OpenCode receives a private configuration path, inline overlay, and FCC API key for that process. Antigravity receives the local Gemini-compatible URL and token in its child environment. Its session settings and model selection remain private to that child process.

References: src/…/environment.py• L10-69 src/…/environment.py• L8-41 src/…/local_http.py• L13-51 src/…/claude_env.py• L11-34 src/…/claude.py• L11-33 src/…/agy.py• L26-51 src/…/opencode.py• L35-62

Managed client sessions

Managed Claude sessions let the application use Claude Code as a long-lived child process for message-driven or programmatic work. A session manager maps conversations to subprocess sessions, while each session launches a task in the configured workspace and turns the client's streamed output into events for the application. The client integration harnesses page describes the related client-facing integration paths.

The manager creates one session for a new conversation and reuses it for later messages. A temporary identifier bridges the time before the client reports its real session identifier. This lets callers submit work immediately while preserving later resume and fork behavior.

Session lifecycle

When a managed task starts, the session builds a command and child environment for the prompt, starts the process, reads output as it arrives, and emits a final exit event. It also reads standard error while reading standard output so a noisy client cannot block the task. Cancellation and explicit removal stop the process and release its ownership.

The process registry is a last-resort safety net. It tracks only FCC-spawned process IDs, removes them after confirmed exit, and attempts to terminate any remaining tracked processes during server shutdown or interpreter exit.

References: src/…/session.py• L29-60 src/…/session.py• L95-245 src/…/session.py• L258-293 src/…/process_registry.py• L1-76

Streamed client events

Managed Claude output uses line-delimited JSON when available. The session parser passes structured events through, reports the first discovered session ID, and preserves non-JSON lines as raw events. Standard error is split into known harmless diagnostics and failure text so expected client notices do not turn into false task errors.

References: src/…/claude.py• L48-55 src/…/claude.py• L163-221 src/…/diagnostics.py• L8-47

Runtime flow

The main paths share one local service but differ in who owns the foreground interaction. The following diagram shows how terminal commands, desktop startup, and interactive clients reach the same server while native clients run as separate child processes.

flowchart TD
    A[fcc-server] --> B[Server supervisor]
    C[fcc-doctor] --> D[Diagnostic report]
    C --> E[Optional clipboard copy]
    C --> F[Integration disconnect]
    G[fcc-desktop] --> H[Desktop singleton check]
    H -->|first instance| B
    H -->|existing instance| I[Open current Admin UI]
    J[fcc-client launcher] --> K[Prepare environment and resources]
    K --> L[Ensure local proxy is available]
    L -->|if absent| R[Platform server owner]
    R --> B
    L --> M[Health and compatibility checks]
    M --> N[Native interactive client]
    N --> B
    O[Managed conversation] --> P[Managed session]
    P --> Q[Claude child process]
    Q --> B
    B --> S[Admin UI and provider runtime]

The server owns the local HTTP boundary. Interactive launchers and managed sessions consume that boundary through child-specific environments, while the desktop shell controls the server's lifetime without changing the client protocol.

References: src/…/commands.py• L71-121 src/…/commands.py• L132-241 src/…/commands.py• L431-460 src/…/desktop.py• L48-162 src/…/desktop_tray.py• L13-67 src/…/runner.py• L91-152 src/…/session.py• L95-245 src/…/doctor.py• L13-44

Change checklist

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

  • Keep the installed script names in pyproject.toml aligned with the entrypoint modules and supported desktop platforms.
  • Keep desktop option handling aligned with platform support. Icon export must remain usable without a tray, while macOS app installation must not be treated as a tray launch.
  • Keep the diagnostic command's report output and optional clipboard path aligned. Clipboard failure must not hide or alter the JSON report written to standard output.
  • Keep the integration disconnect option aligned with each integration's connection owner and recovery data. Cleanup must not start the server or remove FCC's recovery data before all operations succeed.
  • Keep the local URL rules, health check path, external FCC status shape, and child NO_PROXY policy aligned. A mismatch can make a healthy local server look unavailable or route it through an external proxy.
  • Keep launcher environment ownership aligned with each native client's connection variables. A stale variable can override the local proxy without an obvious launch error.
  • Keep OpenCode's process-local configuration, provider-use policy, runtime limits, and FCC-managed standalone mode aligned with the supported OpenCode release. A conflicting user setting can change which configuration the child reads.
  • Keep Antigravity's temporary settings file, cleanup record, native provider mode, model format, and local Gemini-compatible environment aligned. A drift can leave an old FCC connection active, alter user entries, or make the session start without a usable model.
  • Keep each native catalog adapter aligned with the model-list view and capability fields that the client consumes. A catalog can load while silently hiding models or features if those contracts drift.
  • Keep native version and activation checks aligned with the client behavior required by each launcher. A check that is too weak can fail later inside the client.
  • Keep DeepSeek Harness profile and pass-through command rules aligned with its CLI. A change can apply the FCC patch to the wrong subcommand or bypass the required web profile.
  • Keep the DeepSeek Harness patch schema, FCC provider route, and process-local credential reference aligned. A drift can make the client start without a usable FCC model path.
  • Keep server restart and desktop quit paths aligned with application cleanup. A new long-lived child process must remain under the process registry or managed-session owner.
  • Keep temporary launcher resources inside the launch lifetime. Do not make a native client depend on a file that is removed before the child exits.
  • Keep temporary and real managed session IDs mapped together when changing session start or resume behavior.
  • Keep server access-log filtering aligned with every credential-bearing query parameter. A new logging path must not print local API keys.

Important failure modes

TriggerConsequenceGuard
The local proxy health check cannot reach the configured server and no owner can start it.An interactive launcher exits before starting the native client.Start fcc-server or the desktop host first and use the reported local URL.
Concurrent launchers reach startup at the same time.More than one launcher can try to own the server startup unless they share the startup lock.Keep the startup lock and wait-for-health path around server creation.
A second desktop instance cannot acquire the desktop lock.No second tray or server starts; the existing Admin UI is opened instead.Use the existing tray instance as the owner of the local runtime.
A native client binary is missing or fails its compatibility probe.The launcher exits with an install or compatibility message.Install the client and meet the launcher's supported version rule.
Antigravity is below version 1.5.9 or has no routable model.fcc-agy exits before starting the native client.Upgrade Antigravity CLI and keep at least one FCC model available.
The configured port is busy and does not report a valid FCC status.The server refuses to start and identifies the port as occupied by another program or an unknown process.Stop the conflicting program or set PORT to a free port in the managed environment file.
An existing FCC instance is still stopping.A new server does not take over the port immediately.Wait for the old instance to finish or start again after shutdown completes.
The diagnostic command cannot access the desktop clipboard.The JSON report still prints, but it is not copied automatically.Copy the report from standard output or use a desktop with clipboard support.
FCC connection settings or an integration's local files cannot be read or changed during disconnect.The command reports a failure and keeps FCC's installed tool and recovery data available.Correct the settings or permissions, close the related app, and retry or disconnect it manually.
The macOS app installation command receives an unsupported platform or an install error.The app shell is not installed and the command exits with a failure status.Run the install option on macOS and resolve the reported file, value, or subprocess error.
OpenCode is not a stable version 2 release or receives a catalog with no routable models.The launcher exits before starting OpenCode.Use a supported OpenCode release and keep at least one FCC model available.
DeepSeek Harness is below the supported release or receives no routable FCC model.The launcher exits before applying the FCC patch or starting the client.Use DeepSeek Harness >=0.2.0-rc.2 and keep at least one FCC model available.
A client-specific provider overlay or extension cannot activate.The launcher exits before handing control to the interactive client.Keep the client version, private settings, and bundled extension contract aligned.
A child environment retains a conflicting provider URL or proxy setting.The client can bypass FCC or send local traffic through the machine proxy.Use the shared client environment policy and preserve the local NO_PROXY entries.
A credential-bearing query reaches an unfiltered access log.A local API key can appear in FCC log output.Keep the Uvicorn query filter on the access logger and mask key values before formatting.
A managed child is cancelled or the server stops during a task.The child can outlive the request and continue using workspace resources.Stop the session and use the tracked process cleanup as a fallback.
A settings change requests a server restart while the runtime is closing.The new generation is not started.Treat a closed runtime as terminal and start a fresh server or desktop session.
An Admin browser handoff is requested after the server generation starts stopping.The browser is not opened for a stale or closing runtime.Request Admin again after the current FCC instance reports running.

Key files

FileWhy to read it
pyproject.tomlDefines the installed server, client, and desktop entrypoints.
src/…/entrypoints.pyKeeps installed command startup light and routes server and diagnostic commands.
src/…/doctor.pyShows local diagnostics, optional clipboard sharing, and integration disconnect handling.
src/…/clipboard.pyShows the optional clipboard boundary used by the diagnostic command.
src/…/integration_cleanup.pyShows how local editor and desktop integrations are disconnected before uninstall.
src/…/commands.pyShows server supervision, port ownership checks, health-gated Admin opening, restart, and shutdown policy.
src/…/uvicorn_server.pyShows credential-safe server logging and the HTTP server lifecycle callbacks.
src/…/bootstrap.pyShows what the local HTTP service assembles when a server generation starts.
src/…/desktop_entrypoint.pyShows platform gating, icon export, and the macOS app-install entrypoint for the desktop shell.
src/…/desktop.pyShows singleton ownership and coordination between the tray loop and server worker.
src/…/desktop_tray.pyShows the user-facing desktop actions exposed by the native status-area adapter.
src/…/runner.pyShows the common lifecycle for installed interactive clients.
src/…/common.pyShows proxy readiness, startup ownership, child process launch, and exit cleanup.
src/…/agy.pyShows the Antigravity compatibility check, session-only settings, and native launch contract.
src/…/antigravity.pyShows the temporary Antigravity model settings and cleanup of a prior FCC connection.
src/…/opencode.pyShows the OpenCode compatibility check, standalone-mode rule, and process-local launch setup.
src/…/opencode_config.pyShows how FCC models become OpenCode provider data and runtime limits.
src/…/dsh.pyShows the DeepSeek Harness compatibility check, command pass-through rules, and FCC launch setup.
src/…/dsh_config.pyShows how the FCC catalog becomes the temporary DeepSeek Harness provider patch.
src/…/pi_extension.tsShows Pi model discovery and provider registration at client startup.
src/…/codex_model_catalog.pyShows projection of FCC models into the Codex catalog format.
src/…/environment.pyDefines the shared child environment contract.
src/…/local_http.pyDefines direct local requests and local proxy bypass behavior.
src/…/manager.pyShows conversation-to-session ownership and managed session cleanup.
src/…/session.pyShows managed child execution, streamed output, cancellation, and exit handling.
src/…/process_registry.pyShows the fallback cleanup boundary for FCC-spawned processes.