jackwener__opencli/docs/guide/electron-app-cli.md

description

description
How to turn a new Electron desktop app into an OpenCLI adapter

Add a New Electron App CLI

This guide is the fast entry point for turning a new Electron desktop application into an OpenCLI adapter.

If you want the full background and deeper SOP, read:

• CLI-ifying Electron Applications
• Chrome DevTools Protocol
• TypeScript Adapter Guide

When to use this guide

Use this workflow when the target app:

• is built with Electron, or at least exposes a working Chrome DevTools Protocol (CDP) endpoint
• can be launched with --remote-debugging-port=<port>
• should be automated through its real UI instead of a public HTTP API

If the app is not Electron and does not expose CDP, use the native desktop automation pattern instead. See CLI-ifying Electron Applications.

The shortest path

1. Confirm the app is Electron

Typical macOS check:

ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework

If Electron is present, the next step is usually to launch the app with a debugging port.

2. Launch it with CDP enabled

/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=<unique-port>

Then point OpenCLI at that CDP endpoint:

export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:<unique-port>"

3. Start with the 5-command pattern

For a new Electron adapter, implement these commands first in clis/<app>/:

• status.js — verify the app is reachable through CDP
• dump.js — inspect DOM and snapshot structure before guessing selectors
• read.js — extract the visible context you actually need
• send.js — inject text and submit through the real editor
• new.js — create a new session, tab, thread, or document

This is the standard baseline because it gives you:

• a connection check
• a reverse-engineering tool
• one read path
• one write path
• one session reset path

The full rationale and examples are in CLI-ifying Electron Applications.

Recommended implementation workflow

Step 1: Build status

Goal: prove CDP connectivity before touching app-specific logic.

Typical checks:

• current URL
• document title
• app shell presence

If status is unstable, stop there and fix connectivity first.

Step 2: Build dump

Do not guess selectors from the rendered UI.

Dump:

• document.body.innerHTML
• accessibility snapshot
• any stable attributes such as data-testid, role, aria-*, framework-specific markers

Use the dump to identify real containers, buttons, composers, and conversation regions.

Step 3: Build read

Target only the app region that matters.

Good targets:

• message list
• editor history
• visible thread content
• selected document panel

Avoid dumping the entire page text into the final command output.

Step 4: Build send

Most Electron apps use React-style controlled editors, so direct .value = ... assignments are often ignored.

Prefer editor-aware input patterns such as:

• focus the editable region
• use document.execCommand('insertText', false, text) when applicable
• use real key presses like Enter, Meta+Enter, or app-specific shortcuts

Step 5: Build new

Many desktop apps rely on keyboard shortcuts for “new chat”, “new tab”, or “new note”.

Typical pattern:

const isMac = process.platform === 'darwin';
await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
await page.wait(1);

Where to put files

For a desktop adapter, the usual layout is:

clis/<app>/status.js
clis/<app>/dump.js
clis/<app>/read.js
clis/<app>/send.js
clis/<app>/new.js
clis/<app>/utils.js

If the app grows beyond the baseline, add higher-level commands such as:

• ask
• history
• model
• screenshot
• export

What to document when you add a new app

When the adapter is ready, also add:

• an adapter doc under docs/adapters/desktop/
• command list and examples
• launch instructions with --remote-debugging-port
• any required environment variables
• platform-specific caveats

Examples to study:

• docs/adapters/desktop/codex.md
• docs/adapters/desktop/chatwise.md
• docs/adapters/desktop/discord.md

Common failure modes

CDP endpoint exists, but commands are flaky

Usually one of these:

• the wrong window/tab is selected
• the app has not finished rendering
• selectors were guessed instead of discovered from dump
• the editor is controlled and ignores direct value assignment

The app is Chromium-based but not truly controllable

Some desktop apps embed Chromium but do not expose a usable CDP surface. In that case, switch to the non-Electron desktop automation approach instead of forcing the Electron pattern.

You already have a browser workflow and wonder whether to reuse it

If the app exposes a normal web URL and the browser flow is enough, a browser adapter is usually simpler. Use an Electron adapter only when the desktop app is the real integration surface.

Recommended reading order

If you are starting from zero:

1. This page
2. CLI-ifying Electron Applications
3. Chrome DevTools Protocol
4. TypeScript Adapter Guide
5. One concrete desktop adapter doc under docs/adapters/desktop/

Practical rule

Do not start with a large feature surface.

Start with:

• status
• dump
• read
• send
• new

Once those are stable, extend outward.