How to Customize Electron Client Skins with CSS and DevTools
This guide explains why Electron-based desktop AI clients can be re-skinned and how to do it using CSS overrides, DevTools, or remote debugging injection. It includes a complete theme file, a Node.js launcher script, Windows and macOS entry points, advanced styling tips, troubleshooting, and maintenance practices.
How to Customize Electron Client Skins with CSS and DevTools
Key takeaway: The interface of an Electron-based desktop AI client is essentially a web page running in a renderer process. With the built-in developer tools, a piece of CSS can change its appearance. There is no need to purchase any third-party skinning service.
1. From Buying Skins to Building Your Own
In developer communities, changing the skin of an AI desktop client has become a niche but interesting topic. Some users are willing to pay for ready-made themes. This happens for both real reasons and information gaps:
- High usage intensity: These clients have become one of the most frequently opened tools for many developers and knowledge workers. After staring at the screen for long periods, users become much less tolerant of details such as color schemes, fonts, and spacing.
- Default themes cannot please everyone: Light themes may be too bright, dark themes may have insufficient contrast, sidebars may be too wide, and input boxes may have excessive rounded corners. Even an excellent default design cannot satisfy all users at the same time.
- Customization may look harder than it is: Some paid tutorials make the process sound mysterious, leading beginners to believe that low-level source code knowledge or reverse engineering is required.
In reality, the “skin” of such a client is just a set of style rules in the rendering layer. Once you understand the runtime architecture and two mainstream customization approaches, anyone can create a personal theme within ten minutes to an hour and keep refining it based on usage feedback.
This article follows the sequence: principles -> verification -> route comparison -> hands-on practice -> script automation -> maintenance. At the end of the article, there is also a reusable theme configuration template. You can start by simply replacing the colors.
2. Why These Clients Are Naturally Skinable
2.1 Architecture: The UI Is a Web Page, the Shell Is a Desktop Application
Most desktop AI clients available today, whether for Windows or macOS, are built with a hybrid architecture based on Electron, which combines web technologies with a desktop shell. Electron consists of two main parts:
- The underlying Chromium engine: It renders HTML, CSS, and JavaScript into the interface you see.
- The upper Node.js runtime: It provides the main process with operating system capabilities such as file reading and writing, system tray support, global shortcuts, and automatic updates.
After the application starts, the main process handles lifecycle management and window control, and it interacts with the renderer process through IPC, or inter-process communication. The renderer process hosts the business interface, and it is essentially a web page wrapped inside a desktop window.
| Architecture element | What it handles | Skin-related characteristics |
|---|---|---|
| Main process | Window management, shortcuts, tray, automatic updates | Application startup entry points and command-line arguments are handled here |
| Renderer process | All visible UI and interaction logic | The interface is rendered by HTML/CSS, and styles can be overridden at runtime |
| Built-in developer tools, DevTools | Element tree, styles panel, console | You can inspect and modify styles while the app is running |
| Debugging capability | Chrome DevTools Protocol, CDP | External programs can connect to the app and send instructions to the page |
2.2 Three Key Conclusions
- The interface is a web page: All colors, fonts, rounded corners, and spacing are determined by CSS. As long as you can inject a style with sufficiently high priority at runtime, you can override the default appearance.
- The application includes developer tools: Electron integrates Chromium developer tools by default, and they can usually be opened with a keyboard shortcut. They provide the same capabilities as browser developer tools and can be used to debug and modify the frontend.
- The interface can be controlled by external programs: If the application is started with a remote debugging port parameter, an external program can use the debugging protocol to send instructions to the renderer process, including executing JavaScript in the page.
These three points form the technical foundation for the two customization routes described later.
2.3 Verify Compatibility Before You Begin
Different clients may differ in kernel versions, shortcut behavior, and security restrictions. Before starting, verify the following in order:
- Verify developer tools: On macOS, open the client and press
command + option + i. On Windows or Linux, pressCtrl + Shift + I. If the developer tools panel opens, the shortcut has not been disabled. If it does not work, the client may have disabled this entry for security reasons. In that case, use the startup argument approach instead. - Verify whether the interface is web-rendered: In the Elements panel of DevTools, you should see a complete DOM tree made up of elements such as
<div>. The Styles panel should also contain many CSS rules. This strongly suggests that the interface is rendered with web technologies. - Verify the package structure, optional: Look in the installation directory or app bundle for archived files under a
resourcesdirectory, commonly named something likeapp.asar. If such archive files and the corresponding runtime are present, this can also help confirm the architecture. - If you are unsure: Ask the application provider whether the app is built with Electron and whether it supports remote debugging. Then decide which route to use.
3. Two Main Routes: Deep Modification vs. Runtime Injection
| Dimension | Route 1: Modify files inside the app package | Route 2: DevTools / CDP injection |
|---|---|---|
| Modification depth | Deep. You can replace resources and change static files | Shallow. Mostly style overrides, with no impact on application logic |
| Survives restart | Yes | Depends on the injection method. If injected through a launcher, it can survive |
| Survives app upgrade | No. You need to patch it again | The app package remains unchanged, and the script usually needs no changes |
| Code signing | Modifying the app bundle invalidates the signature | Application files are not modified, so the signature is unaffected |
| Learning curve | Higher, because it involves unpacking, repacking, and permissions | Lower, as long as you can write CSS |
| Main risk | Modifying the wrong file may prevent the app from starting | A debugging port introduces local security risk and needs hardening |
Route 1: Modify the Archive Files Inside the Application Package
The idea is to start from the source: unpack, modify, then repack and replace the original file. The general steps are:
- Back up the original file: Copy the archive file first. If anything goes wrong, you can quickly roll back.
- Unpack the archive: Mature unpacking and repacking tools are available in the community, such as the
asarcommand-line tool in thenpxecosystem. A typical command looks likenpx asar extract app.asar ./app-src. - Locate the source of the styles: Search the unpacked directory for global style files or inline style blocks, and identify where theme colors, fonts, and rounded corners are defined.
- Inject custom styles: Append your own rules to the end of the global stylesheet. If you only want to change the skin, try to add new styles without modifying business logic code.
- Repack and replace: Run
npx asar pack ./app-src app.asarto rebuild the archive, replace the original file, and then launch the app to verify.
There are three important issues with this route:
- Signature invalidation: On macOS, modifying any file inside an app bundle invalidates the existing code signature. This may appear as a keychain authorization prompt every time you launch the app. A copied standalone app bundle has the same problem. Some applications also validate file integrity and may refuse to start after modification.
- Upgrade resets changes: Automatic updates download and overwrite local files, so all modifications are lost. You need to patch the new version again.
- Permissions and security: On Windows, directories such as
Program Filesusually require administrator privileges to write. Modifying system-level application files may also be blocked by security software. Make sure the file source is trusted and always keep a backup.
Suitable scenarios: Choose this route only if you need deep customization, such as replacing the application icon or changing the default layout structure, or if you cannot enable debugging through startup arguments.
Route 2: Inject Custom CSS Through DevTools or CDP
If you only want to change colors, fonts, or rounded corners, runtime injection is the most cost-effective approach.
Method A: Temporary Injection Through the DevTools Console
Open DevTools and run the following in the Console panel:
(() => {const id = 'custom-skin-style';let el = document.getElementById(id);if (!el) {el = document.createElement('style');el.id = id;document.head.appendChild(el);}el.textContent = `:root {--bg-base: #0f172a;--text-primary: #e2e8f0;--accent: #6366f1;}`;return !!document.getElementById(id);})();
The page will change immediately, which is useful for quickly testing colors. However, the limitations are also clear:
- The style is lost after a refresh or restart.
- Some single-page applications may rebuild
<head>when switching views, causing the style to be removed. - Some clients filter code pasted into the DevTools console. You may need to manually type
allow pastingbefore execution, depending on the version you use.
Method B: CDP Injection Through a Remote Debugging Port
Close the client, then run the following command in a terminal to start the application with a remote debugging port. Replace the executable path with the actual path on your machine:
# macOS"/Applications/ExampleApp.app/Contents/MacOS/ExampleApp" --remote-debugging-port=9222# Windows, PowerShell& "$env:LOCALAPPDATA\Programs\ExampleApp\ExampleApp.exe" --remote-debugging-port=9222
After starting, open http://127.0.0.1:9222/json in a browser address bar. You will see debugging information for each page target of the application, including addresses you can connect to directly. After connecting to the target with a client that supports the debugging protocol, send a JavaScript snippet to inject the stylesheet and complete the skinning process.
The drawback is also clear: if the injection is not run automatically, the skin will be lost every time the software restarts.
Route 3, Recommended: Write a Launcher Script to Automate Startup and Injection
This route is a compromise between the first two. It avoids invalidating the app signature while remaining reusable:
- The script starts the application with the remote debugging port parameter.
- The script connects to the debugging port and automatically injects the skin when the page is ready.
- For daily use, you only need to open the client through the script or a shortcut created by the script.
Security notice, read this first: Once the debugging port is enabled, other programs on the same machine that know the port address can send instructions to the application page. This is similar to exposing the application’s control interface to local processes. Use the following hardening measures:
- Use it only in a trusted local environment. Access the port only through
127.0.0.1. Do not expose it to the local network or the public internet. - Use the script only to inject CSS. Do not use it to execute scripts from unknown sources.
- Keep skinning limited to appearance-level style overrides. Do not touch application logic, and do not use it to bypass authorization or unlock paid features.
- Enable the port when debugging is needed, and exit the application normally when daily use is complete.
4. Hands-On: One-Click Skinning with a Launcher Script
4.1 Prepare the Theme File, theme.css
A well-structured theme should center on design variables, also known as CSS custom properties, and include a few fallback rules at the end for high-frequency components:
/* ========== 1. Base design variables ========== */:root {/* Background and layers */--bg-base: #0f172a;--bg-elevated: #1e293b;--bg-hover: rgba(148, 163, 184, 0.16);/* Text */--text-primary: #e2e8f0;--text-secondary: #94a3b8;--font-sans: "Inter", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;/* Accent and status colors */--accent: #6366f1;--accent-hover: #818cf8;--success: #22c55e;--warning: #f59e0b;--danger: #ef4444;/* Shapes */--border-color: #334155;--radius-sm: 6px;--radius-md: 10px;}/* ========== 2. Fallback rules for common components, variable names may vary by app and should be adjusted based on the actual DOM ========== */body {background-color: var(--bg-base) !important;color: var(--text-primary) !important;font-family: var(--font-sans) !important;}/* Input fields: the most common harsh white-background issue in dark themes */textarea, input[type="text"], [contenteditable="true"] {background-color: var(--bg-elevated) !important;color: var(--text-primary) !important;border-color: var(--border-color) !important;border-radius: var(--radius-md) !important;}/* Buttons and links */button.primary, .btn-primary {background-color: var(--accent) !important;border-radius: var(--radius-sm) !important;}a { color: var(--accent-hover) !important; }/* Scrollbar: reduce visual distraction during long conversations */::-webkit-scrollbar { width: 8px; height: 8px; }::-webkit-scrollbar-thumb {background: var(--border-color);border-radius: 4px;}
The variable names above are only examples. Different clients use very different naming conventions, and some may not have unified variables at all. You need to identify them one by one using the detection method described in Section 5. Component fallback selectors such as .btn-primary should also be adjusted according to the actual DOM.
4.2 Write the Launcher Script, launch-theme.mjs
Below is an example using Node.js, which works on both Windows and macOS. The core flow is: start the app -> wait for the port to be ready -> connect to a page target -> inject the skin -> monitor reload events:
// launch-theme.mjs - Usage: node launch-theme.mjs <app executable path> [theme file path]import { readFileSync } from 'node:fs';import { spawn } from 'node:child_process';import { setTimeout as sleep } from 'node:timers/promises';const appPath = process.argv[2];const themePath = process.argv[3] ?? new URL('./theme.css', import.meta.url);const PORT = 9222; // Bind to the loopback address onlyif (!appPath) {console.error('Usage: node launch-theme.mjs <app executable path> [theme file path]');process.exit(1);}const css = readFileSync(themePath, 'utf8');// 1. Start the app with a remote debugging portconst child = spawn(appPath, [`--remote-debugging-port=${PORT}`], {detached: true, // Create a separate process group for easier shutdownstdio: 'ignore',});child.on('error', (err) => {console.error('Failed to start the app:', err.message);process.exit(1);});child.unref(); // Let the app continue running after the script exits// 2. Poll the debugging endpoint and get the WebSocket debugger URL of a page targetasync function getPageTarget(timeout = 15000) {const deadline = Date.now() + timeout;while (Date.now() < deadline) {try {const res = await fetch(`http://127.0.0.1:${PORT}/json/list`);const targets = await res.json();const page = targets.find(t => t.type === 'page' && t.webSocketDebuggerUrl);if (page) return page.webSocketDebuggerUrl;} catch { /* The port is not ready yet; retry */ }await sleep(300);}throw new Error('Timed out waiting for the remote debugging port. Check whether the app supports remote debugging.');}// 3. Injection script: reuse an existing style node if present; re-inject after the document is recreatedconst expr = `(() => {const ID = 'custom-skin-style';const CSS = ${JSON.stringify(css)};const paint = () => {const head = document.head || document.documentElement;let el = document.getElementById(ID);if (!el) {el = document.createElement('style');el.id = ID;}if (el.textContent !== CSS) el.textContent = CSS;if (!el.isConnected) head.appendChild(el);};if (document.head) paint();document.addEventListener('DOMContentLoaded', paint);new MutationObserver(() => {if (!document.getElementById(ID)) paint();}).observe(document.documentElement, { childList: true, subtree: true });return true;})()`;// 4. Execute the injection script in the page through the debugging protocolasync function inject(wsUrl) {return new Promise((resolve, reject) => {const ws = new WebSocket(wsUrl); // Built-in in Node.js 22+; no extra dependency neededws.addEventListener('open', () => {ws.send(JSON.stringify({id: 1,method: 'Runtime.evaluate',params: { expression: expr, returnByValue: true },}));});ws.addEventListener('message', (e) => {const msg = JSON.parse(e.data);if (msg.id !== 1) return;ws.close();if (msg.error || msg.result?.exceptionDetails) {reject(new Error(JSON.stringify(msg.error ?? msg.result.exceptionDetails)));} else {resolve();}});ws.addEventListener('error', () => reject(new Error('Unable to connect to the debugging port')));});}// 5. Main flow: inject after the first connection, then re-inject when the page reloadstry {const wsUrl = await getPageTarget();await inject(wsUrl);const ws = new WebSocket(wsUrl);ws.addEventListener('message', (e) => {const msg = JSON.parse(e.data);if (msg.method === 'Page.frameNavigated' && msg.params.frame.parentId === undefined) {console.log('[skin] The page refreshed. Re-injection will happen in 1 second.');setTimeout(() => inject(wsUrl).catch(console.error), 1000);}});console.log('[skin] Skin injection succeeded. Monitoring reloads. Press Ctrl+C to stop the watcher.');} catch (err) {console.error('[skin] Injection failed:', err.message);}
Key points of the script:
detachedplusunref(): The script can exit immediately after execution, while the application continues to run normally. There is no need to keep the terminal occupied.- Error handling: The script checks the debugging port response and the page execution result. If any step fails, it provides a clear message to help with troubleshooting.
- Duplicate injection protection: Each time the injection logic runs, it first checks whether the style node already exists. This avoids stacking duplicate styles.
- Injection success flag: The example returns
true. In real use, you can use checks such asdocument.querySelector('...')to determine whether the skin has taken effect. - Node.js 22+ required: The script relies on capabilities such as
fetchand built-inWebSocket. On older versions, you need to introduce HTTP and WebSocket libraries yourself. - Hover styles may not take effect: CSS injected through
Runtime.evaluateis added dynamically, and the browser may not recompute pseudo-class states such as:hoverand:active. Such rules should be written into the static text oftheme.cssand injected by the launcher. This is why the example puts the CSS into a string rather than inlining it directly.
The script depends on Node.js, which has a relatively large installation package. Developers who want something lighter can use Python or another language together with an appropriate debugging protocol library. The overall flow is the same.
4.3 Configure a Daily Entry Point
Windows: Create a startup batch file and fill in the script path and application path. The paths below are examples only:
@echo offnode "D:\tools\skin\launch-theme.mjs" "C:\Users\Me\AppData\Local\Programs\ExampleApp\ExampleApp.exe"
Pin the batch file shortcut to the taskbar or send it to the desktop. From then on, launch the app from the shortcut. If the node command is not recognized, replace node with the full path to your local node.exe.
macOS: Create a launch.command file and give it execute permission:
chmod +x ~/launch.command
Before running it for the first time, allow calls from Terminal in System Settings -> Privacy & Security. The corresponding startup statement inside the script is:
spawn('/Applications/ExampleApp.app/Contents/MacOS/ExampleApp', [`--remote-debugging-port=${PORT}`,]);
If you want to close the app with one action after the script exits, add the following at the end of the script:
process.on('SIGINT', () => {try {process.kill(-child.pid, 'SIGTERM'); // Close the app process group} catch {}process.exit(0);});
5. Advanced Tips: Make the Skin Fit Your Habits
5.1 Reconnaissance Before Making Changes
Before injection, use the following three methods to understand the application’s style structure:
- Export the page structure: In the DevTools Elements panel, right-click the root node and choose Copy -> Copy outerHTML. Save the DOM for offline analysis.
- Search globally: In the Elements panel, press
Ctrl+F, orcommand + Fon macOS, to search for keywords such asbackgroundor#fff. This helps you quickly locate hardcoded light backgrounds. - Enumerate theme variables: Run the following code in the Console. It lists all CSS custom properties on the root element and their values at once, making it easier to identify variables that need to be overridden:
(() => {const style = getComputedStyle(document.documentElement);const vars = {};for (let i = 0; i < style.length; i++) {const name = style[i];if (name.startsWith('--')) vars[name] = style.getPropertyValue(name).trim();}console.table(vars);return Object.keys(vars).length;})();
5.2 Use prefers-color-scheme for System-Based Themes
CSS supports the prefers-color-scheme media query, which can follow the system appearance and switch automatically. Combined with theme variables, you can add the following to theme.css:
@media (prefers-color-scheme: light) {:root {--bg-base: #f8fafc;--bg-elevated: #ffffff;--bg-hover: rgba(15, 23, 42, 0.06);--text-primary: #0f172a;--text-secondary: #64748b;--border-color: #e2e8f0;}}
The definition order follows CSS cascade rules. When both the earlier dark defaults and the later media query match, the later rule wins. If the application interface is fixed to light mode, you can use this block as the default and then define the dark version with @media (prefers-color-scheme: dark). In this way, when the system switches to light mode, the client interface also changes accordingly.
5.3 Understand the Cascade and Avoid Styles That Do Not Apply
- Prefer overriding variables instead of changing styles one by one: Most modern frontend frameworks extract colors, rounded corners, and similar properties into design variables. Once you find the source of the variable and change it in one place, the effect can apply globally.
- Pay attention to specificity: ID selectors have higher priority than class selectors, and inline styles have higher priority than external styles. Adding
!importantto fallback rules can help you override styles reliably, but avoid using it excessively, because it makes future troubleshooting more difficult. - Pay attention to injection timing: Styles inserted later in
<head>appear later under the same specificity level and override earlier rules. If your skin rules are being overridden by application styles, first check whether injection happened too early. - Use cascade layers when appropriate: Some applications use
@layerto manage styles. If necessary, you can wrap the skin in its own layer to adjust priority.
6. Troubleshooting Common Issues
| Symptom | Common cause | How to handle it |
|---|---|---|
| The keyboard shortcut does not open DevTools | The app has disabled the shortcut | Use startup arguments plus a remote debugging port |
| Console injection fails or is blocked | DevTools paste restriction is enabled | Manually type allow pasting and retry, or use a launcher |
| Injection succeeds, but some elements do not change color | Inline styles, ID selectors, or !important rules are overriding them |
Check the matched rules in the Styles panel and increase the priority of your skin rules |
| Hover or click effects do not work | Styles added dynamically by the script may not trigger pseudo-class recalculation | Put pseudo-class rules in the static text of theme.css and inject them again |
| The skin disappears after refreshing the page | The page was recreated, and the injection logic did not run again | Use the launcher script with MutationObserver or reload event monitoring |
| The app repeatedly asks for the keychain password on startup | The app bundle was modified, and the code signature became invalid | Restore the backup, or switch to the injection approach |
| The skin disappears after an upgrade | The new version overwrote the old files | With Route 1, reapply the patch. With Route 2, no changes are usually needed |
7. Maintenance: Keep the Skin Working Long Term
- Use version control: Manage
theme.cssand the launcher script with a local version control tool. Write down the reason for each adjustment so that it is easier to trace which color version felt most comfortable. - Record compatibility information: In the README, record the client version and kernel version used for adaptation. After the app upgrades, if styles break on a large scale, compare the DOM structure changes against this record first.
- Keep the ability to update and restore: When the client prompts you to upgrade, upgrade normally. Patches for Route 1 should be organized into a one-click executable script so that you can reapply them after an upgrade. For Route 2, you only need to confirm that the app still supports the remote debugging port, and no changes are usually required.
- Respect licenses and boundaries: Customization should only target the appearance of locally installed software. Respect the software license agreement. Do not modify or redistribute the application itself. Do not use it to bypass authorization or any paid restrictions. Also respect the design work of others.
8. Conclusion
Customizing the skin of a desktop AI client is essentially the process of understanding the architecture -> choosing an injection method -> expressing your aesthetic with CSS. The principles are not complicated. What really makes the difference is how familiar you are with the DOM structure and how patient you are when refining the details.
Instead of paying a high price for a skin service whose source code you cannot see, it is better to tune your own tools into the appearance you like best. After all, an interface you look at all day is worth customizing yourself.
