sesy toolkit

Remote Electron development usually breaks in two places: the remote Electron main process crashes because there is no display server, and even when the renderer port exists, there is no native Electron window on your local machine. This repository contains both halves of that fix.

What lives here

• @xgauravyaduvanshii/sesy-guard: the package installed inside the remote Electron project to keep Electron alive in SSH and headless environments
• @xgauravyaduvanshii/sesy: the CLI in cli/ that watches the forwarded port on your local machine and opens a real Electron window locally

Repository: https://github.com/xgauravyaduvanshii/sesy.git
Author: xgauravyaduvanshii <[email protected]>

Repository map

windowworker/
├── README.md                 # toolkit overview
├── package.json              # sesy-guard package
├── src/                      # sesy-guard runtime
├── docs/                     # sesy-guard docs
├── tests/                    # sesy-guard tests
├── cli/                      # full sesy CLI package
│   ├── package.json
│   ├── bin/
│   ├── src/
│   ├── docs/
│   └── tests/
└── .github/                  # repo automation and collaboration files

Architecture

flowchart LR
    A[Remote Electron project] --> B[sesy-guard]
    B --> C[Renderer dev server stays alive]
    C --> D[SSH port forwarding]
    D --> E[sesy CLI on local machine]
    E --> F[Local Electron BrowserWindow]

Package 1: @xgauravyaduvanshii/sesy-guard

@xgauravyaduvanshii/sesy-guard is the remote-side safety layer. It prevents Electron from crashing when there is no X11, Wayland, or usable display stack.

What it does

• detects SSH and headless environments
• injects Electron startup flags before app.whenReady()
• lets the renderer dev server continue booting
• helps teams skip BrowserWindow creation on the server

Typical integration

import { app } from 'electron';
import { initSesyGuard, isSshMode } from '@xgauravyaduvanshii/sesy-guard';

const mode = initSesyGuard();

app.whenReady().then(() => {
  if (!isSshMode()) {
    createWindow();
  }
});

@xgauravyaduvanshii/sesy-guard structure

src/
├── index.js          # public API
├── index.cjs         # CommonJS export
├── index.d.ts        # TypeScript declarations
├── detector.js       # SSH/headless detection
├── injector.js       # Electron flag injection
├── errors.js         # custom error types
└── logger.js         # zero-dependency logger

@xgauravyaduvanshii/sesy-guard key docs

• Getting started
• How it works
• API reference
• Integration guide
• Troubleshooting

Package 2: @xgauravyaduvanshii/sesy CLI

The CLI is the local-side experience. It watches the forwarded localhost port and restores the missing native window on your own machine.

What it does

• loads per-project config from .sesy.json
• waits patiently for the forwarded dev server
• launches a real local Electron window when the port responds
• provides init, watch, status, and doctor commands

CLI flow

sequenceDiagram
    participant Dev as Developer
    participant SSH as SSH tunnel
    participant Port as localhost:8000
    participant Sesy as sesy CLI
    participant Electron as Local Electron

    Dev->>SSH: forward remote renderer port
    Dev->>Sesy: run sesy watch
    Sesy->>Port: poll HTTP endpoint
    Port-->>Sesy: first live response
    Sesy->>Electron: spawn local BrowserWindow
    Electron-->>Dev: native desktop app opens

CLI project structure

cli/
├── bin/sesy.js
├── src/
│   ├── commands/
│   ├── core/
│   ├── utils/
│   └── constants.js
├── docs/
├── tests/
└── README.md

CLI key docs

• CLI README
• Getting started
• How it works
• Configuration
• Troubleshooting

When to use which package

| Situation | Package | |---|---| | Remote Electron crashes immediately on SSH | @xgauravyaduvanshii/sesy-guard | | Renderer is alive but you need a local native window | @xgauravyaduvanshii/sesy CLI | | Full remote Electron development workflow | both together |

End-to-end workflow

1. Install @xgauravyaduvanshii/sesy-guard in the remote Electron project.
2. Add the guard initialization at the top of the Electron main process.
3. Start the remote dev server over SSH.
4. Forward the renderer port to your local machine.
5. Install and run the @xgauravyaduvanshii/sesy CLI locally.
6. Let sesy open the Electron window on your own machine.

Development and verification

Root package

npm install
npm test

CLI package

cd cli
npm install
npm test

Collaboration

This repository also includes:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md

Maintainer

• GitHub: xgauravyaduvanshii
• Email: [email protected]

License

MIT