molecule

Claude Code skills for Electron app QA — design review, visual testing, and performance benchmarking.

molecule does for Electron apps what gstack does for web apps: provides a persistent daemon with an AI-friendly ref system (@e1, @e2) for interacting with your app's UI via accessibility tree snapshots.

Quick Start

git clone https://github.com/ahappydad/molecule
cd molecule
./setup

# In your Electron project:
$MO launch electron/main.cjs
$MO snapshot -i                    # See interactive elements
$MO click @e3                      # Click an element
$MO fill @e5 "Hello world"         # Fill a text input
$MO screenshot /tmp/app.png        # Take a screenshot
$MO main-eval "process.uptime()"   # Execute in main process

Architecture

Claude Code CLI
    └─→ $MO <command>
        └─→ HTTP POST localhost:PORT
            ├─→ Bun.serve() daemon
            │   ├─→ Playwright _electron API
            │   └─→ Accessibility tree → @ref system
            └─→ Your Electron App

molecule launches your Electron app via Playwright's _electron API, maintaining a persistent HTTP daemon for sub-second interactions. The ref system parses the accessibility tree and assigns @e1, @e2, etc. to interactive elements, so Claude can interact with your UI without writing CSS selectors.

Skills

| Skill | Description | |-------|-------------| | /molecule-app | Launch, interact, and screenshot Electron apps | | /molecule-qa | Full QA testing with automated bug fixes | | /molecule-qa-only | QA testing with report only (no fixes) | | /molecule-design-review | Visual QA + CSS fixes with atomic commits | | /molecule-plan-design-review | Plan-mode design review (no browser needed) | | /molecule-design-consultation | Create a complete design system | | /molecule-benchmark | Electron performance metrics (startup, memory, IPC) | | /molecule-canary | Post-update monitoring |

Commands

Interaction

• click <@ref> — Click an element
• fill <@ref> <text> — Fill a text input
• type <@ref> <text> — Type character by character
• press <key> — Press a key combination
• select <@ref> <value> — Select a dropdown option
• hover <@ref> — Hover over an element
• scroll [up|down] [amount] — Scroll the page

Reading

• snapshot -i — Interactive elements with refs
• text [selector] — Get text content
• js <expr> — Execute JavaScript in renderer
• console [--errors] — Read console messages
• network [--errors] — Read network requests
• screenshot [path] — Take a screenshot

Electron-Specific

• launch [main.cjs] — Launch the app
• windows — List all BrowserWindows
• window <id|title> — Switch active window
• main-eval <expr> — Execute in main process
• main-memory — Main process memory usage
• ipc-listen <channel> — Intercept IPC messages
• ipc-log [channel] — Read intercepted IPC
• menu — Read application menu
• menu-click <path> — Trigger a menu item

Connection Modes

Launch mode (default): Full control via _electron.launch() — includes main process access, window management, and IPC interception.

Attach mode: Connect to an already-running app via CDP: $MO launch --attach 9222. Requires the app to be started with --remote-debugging-port=9222. No main process access.

License

MIT