electron — the Electron float runtime environment

Synopsis

The Electron float is a desktop runtime for SLICC that reuses the CLI server in --serve-only mode and injects an overlay shell into any Electron application's window. It combines the full capabilities of the CLI float (WebSocket CDP, unrestricted network, single shell context) with a native desktop app experience.

How It Works

When launched, the Electron float starts the CLI server with --serve-only and a --cdp-port flag. The server does not launch its own Chrome — instead it connects to the Electron app's CDP endpoint. The Electron main process creates a BrowserWindow, loads the target URL, and the overlay injector watches for page targets via CDP, injecting the SLICC overlay shell into each one.

The overlay is a custom element (<slicc-electron-overlay>) rendered inside a Shadow DOM. It provides a collapsible sidebar with tabbed access to chat, terminal, files, and memory — all powered by the CLI server's webapp UI loaded in an iframe.

Default Ports

• CDP port

  9223 (vs 9222 for standalone CLI). Passed via --remote-debugging-port to the Electron app.

• Serve port

  5710 (same as CLI, override with PORT env var)

When launched via Sliccstart, ports are dynamically allocated using a hash of the app path, so multiple Electron apps can run SLICC simultaneously without port conflicts.

Launch Commands

# Dev mode
npm run dev:electron -- /Applications/SomeApp.app

# Via CLI server flags
node dist/node-server/index.js --electron /path/to/app.app --kill --cdp-port=9223

# Via Sliccstart (native macOS GUI)
# Select an Electron app from the list and click "Launch with SLICC"

Overlay Shell Injection

The ElectronOverlayInjector polls CDP for inspectable page targets and connects to each one via WebSocket. For each target it:

1. Enables Runtime and Page domains
2. Bypasses CSP with Page.setBypassCSP
3. Detects the app's theme (light/dark) from a screenshot
4. Evaluates the overlay bootstrap script, which registers custom elements and injects the overlay

If the app's CSP blocks the overlay iframe, the injector reloads the page with CSP bypass active and re-injects. The overlay re-injects on every did-finish-load and did-navigate-in-page event to survive navigation.

Sliccstart Integration

Sliccstart is a native macOS SwiftUI launcher that can launch the Electron float. It scans for installed Electron apps, manages SLICC installation and updates, and handles debug build creation for apps that block remote debugging. Each app gets its own dynamically allocated port pair (serve + CDP), so multiple SLICC-attached apps run independently.

Differences from CLI Float

• CDP port

  Default 9223 (CLI uses 9222)

• Browser launch

  Does not launch Chrome. Runs in --serve-only mode, connecting to an existing Electron app's CDP endpoint.

• Overlay injection

  Injects a floating overlay shell into the target app. CLI uses a dedicated browser tab for the UI.

• Port allocation

  Hash-based dynamic ports when launched via Sliccstart. CLI uses fixed port or PORT env var.

• Managed by Sliccstart

  Can be launched and managed by the native macOS launcher. CLI is started from the terminal.

Differences from Extension Float

• Server

  Electron float requires a server (--serve-only). Extension has zero server.

• CSP

  No CSP restrictions — Page.setBypassCSP disables them. Extension operates under strict MV3 CSP.

• Shell context

  Single shell instance. Extension has two (side panel + offscreen document) that share IndexedDB but not window globals.

• CDP transport

  WebSocket (full bidirectional). Extension uses chrome.debugger API.

• Network

  Full unrestricted network access. Extension is scoped to extension permissions.

• Persistence

  Agent stops when the app closes. Extension's offscreen document survives side panel close.

When to Use Electron Float

• You want a desktop app experience with full CLI capabilities
• You need to attach SLICC to an existing Electron application (Slack, VS Code, Discord, etc.)
• You want overlay-style access to SLICC without leaving the target app
• You need unrestricted CSP and full network access

When to Use CLI Instead

• Headless or server-based scenarios (CI, remote machines)
• Remote access via SSH or port forwarding
• No Electron app to attach to — just need a standalone coding agent
• Scripted or automated workflows

When to Use Extension Instead

• Zero server footprint — everything runs in the browser
• You prefer working within an existing Chrome workflow
• Agent persistence matters — the extension's offscreen document survives panel close
• You don't need to attach to Electron apps

See Also

float(1) — overview of all runtime environments. cone(1) — the main agent. scoop(1) — sub-agent isolation.