Use the highest layer that fits.

Choose the highest layer that fits.

Most Electron products should begin with @vibecook/ghosttea-electron and @vibecook/ghosttea-react/workspace.

Electron quickstart

ghosttea crosses Electron's three security boundaries deliberately. The main process owns the backend, preload forwards transferred ports, and the renderer owns the UI.

1. Main process

import { app, BrowserWindow } from "electron";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { GhostteaElectronBackend } from "@vibecook/ghosttea-electron/main";

await app.whenReady();

const daemonName = process.platform === "win32" ? "ghosttead.exe" : "ghosttead";
const preloadPath = fileURLToPath(new URL("./preload.cjs", import.meta.url));
const backend = new GhostteaElectronBackend({
  mode: "managed",
  daemon: {
    binary: {
      kind: "executable",
      path: join(process.resourcesPath, "bin", daemonName),
    },
  },
});

await backend.start();

const window = new BrowserWindow({
  webPreferences: {
    preload: preloadPath,
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
});

window.webContents.on("did-finish-load", () => {
  backend.attachRenderer(window.webContents);
});

app.on("before-quit", () => backend.stop());

In development, the binary option may use { kind: "cargo", manifestPath, release }. Packaged applications should stage the release executable in their resources.

2. Preload

import { ipcRenderer } from "electron";
import { forwardGhostteaRendererPorts } from "@vibecook/ghosttea-electron/preload";

forwardGhostteaRendererPorts(ipcRenderer);

3. Renderer runtime

import {
  createGhostteaTerminalRuntime,
  waitForGhostteaRendererPorts,
} from "@vibecook/ghosttea-react";
import "@vibecook/ghosttea-react/styles.css";
import "@vibecook/ghosttea-react/workspace.css";

export const terminalRuntime = createGhostteaTerminalRuntime({
  ports: waitForGhostteaRendererPorts(),
  clientBuild: "my-app",
  platform: {
    writeClipboard: (text) => window.app.writeClipboard(text),
    forceCanvasFallback: () => false,
    setForceCanvasFallback: () => {},
    reload: () => window.location.reload(),
  },
});

window.addEventListener(
  "beforeunload",
  () => terminalRuntime.dispose(),
  { once: true },
);

4. React workspace

import { GhostteaProvider } from "@vibecook/ghosttea-react";
import { GhostteaWorkspace } from "@vibecook/ghosttea-react/workspace";
import { terminalRuntime } from "./terminal";

export function App() {
  return (
    <GhostteaProvider runtime={terminalRuntime}>
      <GhostteaWorkspace
        platform={window.app.terminalPlatform}
        storageKey="my-app:terminal-workspace"
      />
    </GhostteaProvider>
  );
}

Electron API

@vibecook/ghosttea-electron owns service lifecycle, the utility-process bridge, and a control-only automation client.

GhostteaElectronBackend

Managed vs. external

// ghosttea owns the process.
{ mode: "managed", daemon: { binary: { kind: "executable", path } } }

// Your application owns the Rust service.
{ mode: "external", connection: { controlSocket, frameSocket, authToken } }

External mode is the right choice when one Rust process shares a Truffle node or other infrastructure across several application services.

React API

@vibecook/ghosttea-react owns the renderer runtime, terminal surfaces, input routing, and worker-owned WebGPU renderer.

Runtime

Use waitForGhostteaRendererPorts() for the ports transferred by the Electron preload. The runtime connects lazily and can be shared by any number of surfaces in one window.

Common methods

GhostteaProvider

Makes the shared runtime available to TerminalSurface and GhostteaWorkspace.

TerminalSurface

Mounts one accessible canvas and invisible text input. The component handles keyboard, IME, pointer, selection, scrollbar, focus, and grid resize behavior.

GhostteaWorkspace

Adds persisted split panes, zoom, themes, terminal focus, Ghostty-style shortcuts, remote-session browsing, and an optional application sidebar.

Node automation client

@vibecook/ghosttea-client controls sessions without Electron or frame rendering.

import { GhostteaAutomationClient } from "@vibecook/ghosttea-client";

const client = new GhostteaAutomationClient({
  controlSocket,
  authToken,
});

const session = await client.createSession({
  executable: "/bin/zsh",
  args: [],
  environment: {
    mode: "clean",
    variables: { PATH: "/usr/bin:/bin" },
  },
  cols: 120,
  rows: 40,
  persistence: "terminate-with-app",
});

const result = await client.pasteAndSubmit(
  session.id,
  "printf 'hello from ghosttea\\n'",
);

if (!result.accepted) {
  console.log("A human typed first; automation yielded.");
}

High-level methods

The client never opens the frame socket, attaches a view, or claims resize authority.

Browser control client

@vibecook/ghosttea exports ControlClient, a typed request, notification, and event layer over a transferred MessagePort. It is used by the React runtime and is available for custom renderers.

Call request(command, timeoutMs?) for a response, notify(command) for fire-and-forget input, and dispose() when the renderer closes.

Protocol and frames

Use these packages only when building a custom client or renderer:

• @vibecook/ghosttea-protocol — control commands, events, session types, and strict runtime guards.
• @vibecook/ghosttea-frame — bounded decoder for binary TRF1 terminal frames and sections.

Frame headers carry session, layout, sequence, and terminal revisions. Treat gaps as a request for an authoritative full snapshot rather than trying to merge around them.

Rust embedding

ghosttea is the transport-neutral service; ghosttea-core is the platform-neutral terminal model.

use ghosttea::{TerminalService, TerminalServiceConfig};

TerminalService::new(TerminalServiceConfig {
    control_socket,
    frame_socket,
    auth_token,
})
.with_text_engine(text_engine)
.run()
.await?;

Applications that own endpoint permissions and startup order can bind listeners and call serve(TerminalServiceListeners). A host-owned TerminalMesh adds remote discovery and sessions without coupling the service to Truffle.

Published crates

Native Apple stack

GhostteaKit targets iOS 18.1+ and macOS 14+. It composes the shared Rust core with Swift actors, Metal rendering, direct SSH, Truffle shared sessions, and a platform-neutral workspace model.

Start with the GhostteaKit package guide. The production app is implemented and device-tested; external distribution qualification remains in progress.

Sessions

A local session owns one PTY, one Ghostty terminal model, one ordered input actor, and zero or more attached views. A remote session is a local logical replica of a terminal whose PTY remains authoritative on another host.

Environment policy

• { mode: "inherit", overrides } — normal shell behavior with private ghosttea and transport variables removed.
• { mode: "clean", variables } — an explicit environment for agents and isolated tools.

Every session summary includes identity, grid, executable, metadata, activity, and classified exit information.

Input and resize authority

Each attached view receives an attachment epoch. Input sequences deduplicate retries; control epochs reject stale resize owners; layout epochs keep frames aligned with the canonical PTY size.

Automation does not attach a view or claim size. It commits only if no human input was accepted after the automation client observed the human-input epoch.

Security defaults

• Renderer windows remain sandboxed with context isolation and no Node access.
• Control and frame endpoints require the same random bearer token.
• Unix sockets live under a private runtime directory.
• Windows named pipes use a current-user-only protected DACL.
• Private service and transport variables are removed from inherited PTYs.
• Remote peers are read-only unless the host grants write access deliberately.
• Apple credentials persist only as opaque, device-only Keychain references.

Local authentication is service-wide, not command-scoped. Applications that require per-client authorization should place a policy boundary in front of the service.

Platform matrix

Electron 35+ and React 19+ are supported peer ranges. Node clients require Node 22+; Rust crates declare Rust 1.88 as their minimum.