workbuddy-skin-studio

name

workbuddy-skin-studio

description

Apply a reversible theme/skin to the WorkBuddy desktop app (Tencent AI office agent) via local Chromium DevTools Protocol (CDP) injection. Use when the user wants to change WorkBuddy's appearance/theme/skin, references an open-source WorkBuddy theming project by GitHub URL, or says phrases like "帮我换 WorkBuddy 主题/皮肤", "用这个开源项目帮我更换 WorkBuddy 的主题", or "change my WorkBuddy theme". Never modifies app.asar, the official install directory, or code signing.

WorkBuddy Skin Studio

Reversible WorkBuddy desktop theming through local CDP injection. The tool restarts WorkBuddy with --remote-debugging-port=9223, discovers its renderer (renderer/index.html), and injects CSS + a 🎨 theme menu into the live UI. No official files are touched.

When this skill applies

• The user gives you a GitHub URL for workbuddy-skin-studio (or similar) and asks you to install / apply / use it to theme WorkBuddy.
• The user wants to change WorkBuddy's look (color theme, background image, custom uploaded image) without editing the official app.
• The user reports the theme disappeared after a WorkBuddy restart and wants it reapplied, or wants to revert to the native look.

Prerequisites

• WorkBuddy desktop installed (this tool themes the desktop app, not web).
• Node.js 18+ on PATH (the injector is plain Node, cross-platform).
• macOS or Windows. (Linux is not supported by WorkBuddy's desktop build.)
• Warn the user once: applying restarts WorkBuddy and any unsaved in-app work is lost. Ask them to save first.

Platform detection (run first)

• macOS: shell uname returns Darwin, or $OSTYPE starts with darwin.
• Windows: PowerShell $IsWindows is $true, or $env:OS is Windows_NT.
• Choose the matching branch below.

Workflow — macOS

1. Clone / open the repo, then run the launcher (double-click works, or CLI):

   # default theme (miku-light)
   ./scripts/apply.command
   
   # or a specific theme via the cross-platform CLI
   node src/cli.mjs apply --theme genshin-night
   

   apply.command quits WorkBuddy, relaunches it with the CDP port, waits for the debugger, and injects the skin.

2. Verify:

   node src/cli.mjs status
   

   Expect an injected/active state and the WorkBuddy renderer listed.

3. A 🎨 button appears at the top-right of WorkBuddy. Tell the user they can switch themes, upload a custom image, or revert to native from that menu.

Workflow — Windows

1. From the repo directory, run in PowerShell (not cmd):

   # default theme (miku-light)
   .\scripts\apply.ps1
   
   # or a specific theme
   .\scripts\apply.ps1 -Theme genshin-night
   

   If you hit an execution-policy error, run once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then retry.

2. If apply.ps1 cannot locate WorkBuddy.exe, run the locator and follow its printed hint (often you just need to launch WorkBuddy once so the path is registered):

   .\scripts\find-workbuddy.ps1
   

3. Verify:

   node src/cli.mjs status
   

4. Same 🎨 menu appears top-right in WorkBuddy.

Choosing a theme

• List available themes: node src/cli.mjs list (macOS) / same via PowerShell.
• Built-ins include miku-light, miku-488137, genshin-dawn, genshin-night, deepspace-dawn, deepspace-star, naruto-hokage, naruto-sasuke, wuthering-echo, wuthering-tide.
• If the user names a mood/character (e.g. "dark Genshin"), map it to the closest id, or just apply the default and let them pick from the 🎨 menu.
• Custom image: node src/cli.mjs create --image "/path/to/hero.webp" --name "My Skin" then node src/cli.mjs apply --theme my-skin. The in-app 🎨 menu also supports "＋ 自定义图片" with automatic color extraction.

Pause / restore to native

# macOS
./scripts/pause.command

# Windows (PowerShell)
.\scripts\pause.ps1

This removes the injected skin and relaunches WorkBuddy normally. The official install is always left untouched.

Guardrails

• Never replace, edit, or take ownership of WorkBuddy.app, app.asar, or the Windows install directory. This tool only injects into the live renderer.
• CDP binds to loopback 127.0.0.1 only. Tell the user not to run untrusted local software while a skin is active (Chromium CDP has no same-user auth).
• Injection lives for the renderer's lifetime. After a manual WorkBuddy restart the skin disappears by design — re-run apply to bring it back.
• Do not import README/preview screenshots or images with baked-in UI as a theme background; use clean wallpapers / character art.

Checks (sanity before reporting done)

node src/cli.mjs doctor   # platform, app path, CDP port, renderer hint
node src/cli.mjs status   # injection state
node --check src/cli.mjs  # syntax

doctor should report the correct platform, a found WorkBuddy app, and the renderer hint renderer/index.html.

Resources

• src/cli.mjs — entry point: list / create / apply / status / pause / doctor.
• src/cdp-client.mjs — CDP connection + renderer discovery.
• src/skin-css.mjs — --cb-* variable overrides + background + container transparency.
• src/skin-menu.mjs — the 🎨 in-app menu (switch / upload / delete / native).
• src/injector.mjs — idempotent CSS+menu injection and removal.
• src/constants.mjs, src/theme-schema.mjs, src/theme-store.mjs — config & theme model.
• scripts/apply.command / pause.command — macOS launchers.
• scripts/apply.ps1 / pause.ps1 / find-workbuddy.ps1 — Windows launchers.
• themes/ — 10 built-in theme folders (theme.json + hero.webp).
• README.md — full human-readable documentation.

One-line summary for the user

"I cloned workbuddy-skin-studio, restarted WorkBuddy in debug mode, and injected the theme. Use the 🎨 button (top-right) to switch or revert. Re-run apply if you restart WorkBuddy manually."