How to use the Electron Desktop App Automation agent skill

What the electron skill lets an agent do

A skill is a folder of instructions that an AI agent loads when a task matches its description. This one covers desktop apps built on Electron. Once the app is running with its debugging port open, the agent works through a loop: launch, connect, snapshot the interface to find elements, interact with them, and re-snapshot after anything changes.

The skill is useful for developers who want an agent to test their own Electron application end to end, and for power users who want to automate repetitive clicking or data pulling in a desktop app that has no API.

• Read a snapshot of the app's interactive elements
• Click, fill forms and press keys
• Take screenshots, including full-window and annotated versions
• Extract text and save snapshots as JSON
• Switch between windows and webviews
• Control several apps at once using named sessions

Install the electron skill

Download the ZIP for the skill from this page and unzip it. The skill is a folder containing SKILL.md. Put that folder in one of these locations:

For a personal install available across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the agent-browser tool and check requirements

The skill depends on the agent-browser CLI, which the agent calls through Bash as agent-browser or npx agent-browser. You also need the target Electron app installed locally, and shell access on macOS, Linux or Windows to run the launch commands.

The skill's SKILL.md lists the allowed Bash commands as agent-browser and npx agent-browser. Check the agent-browser project for its own installation instructions.

• agent-browser CLI available as agent-browser or npx agent-browser
• The Electron app installed locally and able to accept --remote-debugging-port
• Shell access on macOS, Linux or Windows

Launch the app with remote debugging enabled

Every Electron app accepts the --remote-debugging-port flag because it is built into Chromium. The flag must be present at launch time. If the app is already running, quit it first and then relaunch it with the flag.

The source gives these launch examples for macOS. Each app uses its own port in the examples.

• Quit the app completely if it is already running
• Relaunch it with the flag so the debugging port is open
• Use a different port for each app you run at the same time

Connect and run the basic workflow

Once the app is running with the flag, connect agent-browser to the port. After connect, later commands target the connected app without needing --cdp. The core loop is snapshot, then interact using element refs, then re-snapshot after navigation or state changes.

Two other connection options appear in the source: passing --cdp with a port on each command, and --auto-connect to discover a running Chromium-based app.

• Connect with agent-browser connect 9222
• Snapshot with agent-browser snapshot -i to list interactive elements
• Click an element by its ref, such as @e5
• Re-snapshot after the interface changes

Work with multiple windows and apps

Electron apps often have several windows or webviews. The tab command lists them, and you can switch by index or by URL pattern. Webviews appear in the list with type webview. Note that webview support works through a raw CDP connection.

To control several apps at once, give each connection a named session. Each app then gets its own independent snapshots and actions.

• List targets with agent-browser tab
• Switch by index with agent-browser tab 2
• Switch by URL pattern with agent-browser tab --url "*settings*"

Trigger the skill with natural requests

You do not need to type commands yourself. The skill loads when your request matches its description. Plain requests that name an app or describe a desktop task work well. The source lists these trigger phrases: automate Slack app, control VS Code, interact with Discord app, test this Electron app, connect to desktop app.

Name the app and say what you want done. The agent will check that the app can be launched with a debugging port and then run the workflow.

• "Automate my Slack app to find unread messages from my team"
• "Control VS Code and open the settings tab"
• "Test this Electron app and tell me if the login form breaks"
• "Connect to the desktop app and take a screenshot of its main window"

Troubleshoot common problems

Most failures come from the app not running with the debugging flag or from the port being in use. The source suggests the following checks.

• Connection refused or cannot connect: confirm the app was launched with --remote-debugging-port=NNNN; if it was already running, quit and relaunch it
• Check whether another process holds the port with lsof -i :9222
• App launches but connect fails: wait a few seconds after launch before connecting
• Elements missing from the snapshot: the app may use several webviews, so list targets with agent-browser tab and switch to the right one
• Cannot type in a field: try agent-browser keyboard type "text", or agent-browser keyboard inserttext "text" for custom input components

Safety notes before you run it

The skill runs scripts, so review what the agent executes. It does not use the network according to its listing. The bigger risk is the debugging port itself: while it is open, it is unauthenticated, and other local processes could reach a relaunched app that has it enabled.

Only use the skill on accounts or messages you control. The agent can read and send content as you, and automating an app may breach its terms of service. Avoid sensitive work while a debugging port is open.

• The skill runs scripts; review them before use
• Keep the debugging port closed when you are not automating
• Do not use it on accounts or messages you do not control
• Check each app's terms of service before automating it
• Avoid sensitive work while the port is open