CherryHQ/cherry-studio / .agents/skills/cherry-electron-dev
cherry-electron-dev
VerifiedDevelop, fix, profile, and test PRs in a tracked Cherry Studio Electron instance. Use for implementation, UI and interaction work, runtime debugging, DevTools inspection, performance analysis, and interactive PR verification with a test report. Reuse a verified workspace instance and manage its lifetime according to the selected workflow.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.3 KB |
| references/electron-instance.md | markdown | 7.9 KB |
| references/performance-debugging.md | markdown | 14.5 KB |
| references/pr-testing.md | markdown | 5.3 KB |
references/electron-instance.md
View on GitHub# Electron Instance Management
Use this as the single runtime procedure for development and PR testing in
`cherry-electron-dev`.
## Contents
- Session policy and scratch data
- Verify or discover an instance
- Bind CDP to the exact target
- Gracefully replace an instance
- Start and track a debug instance
- Finish or recover
- Troubleshooting
## Session policy and scratch data
Choose the caller's policy before touching Electron:
| Policy | Use | Finish |
| --- | --- | --- |
| `persistent` | Ongoing development | Leave a healthy instance running |
| `ephemeral` | A bounded PR test | Stop only the instance started by this test |
Treat pre-existing processes as user-owned. Preserve `userData`, databases,
caches, and preferences unless the user explicitly requests a reset.
Use `.context/cherry-electron-dev/` for runtime state and artifacts. The
repository ignores this path, and `mkdir -p` creates it in Conductor and
ordinary clones:
```bash
mkdir -p .context/cherry-electron-dev
```
Track the active instance in `.context/cherry-electron-dev/instance.json` with:
- workspace path and Git HEAD at launch
- `persistent` or `ephemeral` policy and `user` or `agent` ownership
- `launch_purpose` (`development`, `pr-test:<number>`, or `external`)
- `workflow_relation` (`started` or `borrowed`)
- Electron PID, runner PID/session, and process group
- CDP and main-process inspector ports
- exact main-window target URL
- development profile suffix
- launch command, log path, and start time
The file is a hint, not proof. Revalidate it before every UI operation.
At the start of a new workflow, an already-running instance is `borrowed` even
when the same agent launched it during an earlier instruction.
## Verify or discover an instance
Reuse the record only when all checks pass:
1. The Electron PID is alive.
2. Its cwd is the exact current workspace.
3. The recorded CDP listener belongs to that PID.
4. `/json/list` contains the recorded Cherry Studio target.
5. When exact checked-out code matters, the launch Git HEAD matches current
HEAD; otherwise restart instead of relying on HMR for main-process changes.
```bash
lsof -a -p <ELECTRON_PID> -d cwd -Fn
lsof -nP -a -p <ELECTRON_PID> -iTCP:<CDP_PORT> -sTCP:LISTEN
curl -fsS http://127.0.0.1:<CDP_PORT>/json/version | jq .
curl -fsS http://127.0.0.1:<CDP_PORT>/json/list | \
jq '.[] | {id, type, title, url}'
```
If the record is missing or stale, discover before launching:
```bash
ps -axo pid=,ppid=,pgid=,command= | \
rg -i 'Cherry Studio|CherryStudio|electron-vite|remote-debugging-port'
lsof -nP -iTCP -sTCP:LISTEN | rg 'Electron|Cherry|:9222|:5173'
lsof -a -p <ELECTRON_PID> -d cwd -Fn
ps -o pid=,ppid=,pgid=,command= -p <PID>,<PARENT_PID>
```
Ignore candidates that cannot be tied to this workspace. A packaged app and
another checkout are not interchangeable. Never infer ownership from an open
port alone.
If a candidate passes every applicable check, adopt it immediately instead of
launching:
1. Attach to its verified CDP endpoint.
2. Write or refresh `instance.json` with its live identity and
`workflow_relation: borrowed`.
3. Preserve a trustworthy existing policy and ownership. Without a trustworthy
record, treat a pre-existing process as `user` owned and `persistent`.
4. End the launch path. Start another instance only when no suitable candidate
exists or replacement is required.
## Bind CDP to the exact target
Use the verified CDP endpoint exclusively. List targets and match URL and
title; never assume target index `0`. The normal main target is titled
`Cherry Studio` and uses:
```text
http://localhost:5173/windows/main/index.html
```
If the dev server selects another port, require the same
`/windows/main/index.html` path and record the exact URL. Re-list after windows
open or close. Do not navigate a target unless navigation is part of the test.
Use Playwright/CDP or optional `agent-browser`. Do not install a global CLI just
for a task, and do not launch another instance because one controller is
unavailable.
Never pass `Electron`, `com.github.Electron`, or a `node_modules` Electron.app
path to Computer Use or another app-control API. Shared Electron identifiers
can launch or select the wrong checkout.
## Gracefully replace an instance
Replace only when current-workspace code or required CDP access is unavailable.
Before replacing a user-owned process, explain why and record its PID, command,
cwd, parent/runner, PGID, and ports.
Send `SIGTERM` to the exact Electron main PID and wait up to eight seconds:
```bash
kill -TERM <ELECTRON_PID>
for _ in $(seq 1 16); do
kill -0 <ELECTRON_PID> 2>/dev/null || break
sleep 0.5
done
kill -0 <ELECTRON_PID> 2>/dev/null && echo "still running"
```
If Electron exits but its verified same-workspace runner remains, terminate
that PID separately. Never use broad `pkill`, kill arbitrary port owners, or
signal a process group before inspecting every member.
Do not escalate automatically to `SIGKILL`. Report the remaining PID and logs
and ask before forcing a process that may be migrating, backing up, or
preventing quit. Verify the old PID and ports are gone before replacement.
## Start and track a debug instance
Read `package.json` for the current debug command. If its default CDP or
inspector port belongs to an unrelated process, choose free ports and change
only those arguments; do not kill the owner.
Prefer a managed terminal session. With a terminal tool such as
`exec_command`, request a PTY and short initial yield, retain its returned
session ID, and let this command continue:
```bash
pnpm debug 2>&1 | tee .context/cherry-electron-dev/electron.log
```
Do not run that command as an ordinary blocking call. If no managed-session
tool exists, use a recorded background runner:
```bash
nohup pnpm debug >.context/cherry-electron-dev/electron.log 2>&1 &
echo $!
```
Immediately record the returned runner PID. Resolve and record the real
Electron PID and PGID after launch.
Keep the existing development profile for `persistent` work. For an isolated
PR test, set a distinct `CS_DEV_USER_DATA_SUFFIX` and record it.
Wait for the selected CDP endpoint, then identify and record the exact target:
```bash
for _ in $(seq 1 60); do
curl -fsS http://127.0.0.1:<CDP_PORT>/json/version >/dev/null && break
sleep 0.5
done
curl -fsS http://127.0.0.1:<CDP_PORT>/json/list | \
jq '.[] | {id, type, title, url}'
```
Write `instance.json` only after PID, cwd, listener ownership, and target checks
pass. Give a new instance `workflow_relation: started`; never reclassify a
borrowed instance as newly started.
## Finish or recover
For `persistent`, leave healthy user-owned and agent-owned instances running.
For `ephemeral`, stop an instance only when all of these are true:
1. Its verified record has `workflow_relation: started`.
2. Its verified record still says `ephemeral` and `agent` owned.
3. Its PID, cwd, and launch purpose still match the current test.
Leave every borrowed instance running, regardless of whether its existing
ownership is `user` or `agent`.
If an unexpected window or PID appears:
1. Stop UI actions.
2. Identify only the new PID by command and cwd.
3. Gracefully stop that verified unexpected PID.
4. Revalidate the tracked PID, cwd, CDP listener, and target.
5. Resume only through the tracked CDP endpoint.
Never close all Electron processes to recover from a targeting mistake.
## Troubleshooting
| Symptom | Action |
| --- | --- |
| CDP works but the page is missing | Re-list targets and match URL/title; splash, migration, settings, detached tabs, and mini-apps are separate targets. |
| Debug launch exits | Inspect the recorded log for a profile lock, native rebuild, database/startup failure, or port collision; confirm the old PID exited. |
| Splash or migration is stuck | Read startup logs and wait; do not bypass, reset, or force-close without understanding its phase. |
| CDP automation is unavailable | Use logs/source when sufficient. If UI evidence is essential, explain why and use the replacement procedure; never fall back to generic Electron control. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| webapp-testinganthropics/skillsToolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| browser-testing-with-devtoolsaddyosmani/agent-skillsTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| ci-cd-and-automationaddyosmani/agent-skillsAutomates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |