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