Custom Background Images

Works with Visual Studio Code & Cursor

Bring custom backgrounds to every corner of your workbench
editor · sidebar · panel · agent sidebar — live preview, per-region controls, one-click apply

Custom Background Images lets you personalize the VS Code and Cursor workbench with your own photos — tune opacity, blur, brightness, and grayscale per region, preview the full layout before committing, then apply with one reload.

Features · Getting started · How it works · Commands · Development · License · Feedback

Highlights

How to Use

Features

• Four independent regions — Editor, Sidebar, Bottom Panel (Terminal, Problems, Output, …), and Agent / Secondary Sidebar each get their own image and style settings.
• Rich per-region controls — Opacity, blur, brightness, grayscale, background size (cover / contain / auto), and position presets.
• Live layout preview — Open a simulated workbench that updates in real time as you adjust sliders in the sidebar.
• Sidebar settings panel — Pick images, toggle regions, and manage all options from a dedicated activity-bar view.
• Safe apply workflow — Preview first, then Apply & Reload when you are happy with the result.
• One-click disable — Remove injected styles and restore the original workbench on disable or uninstall.
• Cursor agent support — Dedicated handling for the unified agent sidebar, including glass-surface transparency overrides.
• Elevated write fallback — If the workbench file is not writable, the extension offers an admin / sudo retry path.

Requirements

Web / remote hosts: Only the desktop Electron build is supported. Browser-based or remote-only sessions cannot be patched the same way.

Getting started

Install

1. Install from the Marketplace

Open the Extensions view in VS Code or Cursor, search for Custom Background Images, and click Install.

Or use the Marketplace link:

2. Install from the terminal

VS Code:

code --install-extension HadiHajihosseini.custom-background-images

Cursor:

cursor --install-extension HadiHajihosseini.custom-background-images

3. Install from a release (.vsix)

1. Download the latest custom-background-images-1.0.1.vsix from Releases.
2. Install the file:

VS Code:

code --install-extension /path/to/custom-background-images-1.0.1.vsix

Cursor:

cursor --install-extension /path/to/custom-background-images-1.0.1.vsix

You can also open the Extensions view, choose Install from VSIX…, and select the downloaded file.

3. Reload the window when prompted.

Configure your backgrounds

1. Open the Custom Background view on the activity bar.
2. For each region you want to customize:
   • Click Choose Image and select a file from disk.
   • Adjust Opacity, Blur, Brightness, and other sliders.
   • Toggle Enabled for that region.
3. Click Preview Layout to see a live mock of the full workbench.
4. When ready, click Apply & Reload to patch the editor and reload the window.

On first launch, if a patch is needed, you may see a prompt: Apply and Reload or Later.

If apply fails due to permissions, choose Retry with Admin/Sudo when prompted.

How it works

User picks images  →  stored in extension global storage
        ↓
Settings panel / preview webviews (live UI)
        ↓
CSS + mount script generated per enabled region
        ↓
workbench.html patched (versioned marker block)
        ↓
Window reload  →  backgrounds rendered in real workbench

1. Store — Selected images are copied into the extension’s global storage directory (one file per region selection).
2. Configure — Region settings persist in extension global state (backgroundSettings).
3. Generate — A CSS injection script is built for each enabled region, using vscode-file:// URLs for local image access.
4. Patch — The script is inserted into workbench.html inside a versioned HTML comment marker (custom-background-images@1.0.1).
5. Reload — After reload, injected styles attach background overlays via pseudo-elements (and a DOM mount script for the agent sidebar).
6. Restore — Disable & Reload, uninstall, or a legacy re-apply replaces the marker block and removes the patch.

Agent / secondary sidebar

The agent area uses additional logic beyond standard CSS overlays:

• CSS variable overrides to make glass / composer surfaces transparent.
• A MutationObserver-driven mount script that inserts an image overlay when the agent DOM is created or updated.

This keeps backgrounds visible behind Cursor’s agent UI and the unified secondary sidebar.

Supported regions

Per-region settings

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for Custom Background.

Configuration

All user-facing settings are managed through the sidebar panel. One VS Code setting is exposed:

Example in settings.json:

{
  "customBackgroundImages.enabled": true
}

Where data is stored

Project structure

CustomBackgroundVsCodeExtension/
├── media/                    # Webview UI assets
│   ├── icon.png              # Marketplace and activity bar icon (128x128)
│   ├── icon-large.png        # README and promotional display (512x512)
│   ├── panel.css / panel.js  # Settings sidebar webview
│   └── preview.css / preview.js
├── src/
│   ├── extension.ts          # Activation, commands, providers
│   ├── configManager.ts      # Global state for region settings
│   ├── imageStorage.ts       # Image copy, URLs, data URIs
│   ├── types.ts              # Region types and defaults
│   ├── uninstall.ts          # Restore workbench on uninstall
│   ├── panel/
│   │   ├── BackgroundPanelProvider.ts
│   │   └── buildPanelState.ts
│   ├── preview/
│   │   └── PreviewPanel.ts
│   └── patch/
│       ├── patchApplier.ts   # Apply / disable orchestration
│       ├── htmlPatcher.ts    # Read / write workbench.html
│       ├── cssGenerator.ts   # CSS and agent mount script
│       └── vscodePaths.ts    # Resolve workbench.html path
├── package.json
├── tsconfig.json
└── .vscodeignore

Development

Prerequisites

• Node.js 18+
• npm
• VS Code or Cursor for Extension Development Host debugging

Clone and build

git clone https://github.com/hadiMh/CustomBackgroundVsCodeExtension.git
cd CustomBackgroundVsCodeExtension
npm install
npm run compile

Press F5 in VS Code or Cursor to launch an Extension Development Host with this folder as extensionDevelopmentPath.

Scripts

Package a VSIX

npm install -g @vscode/vsce
npm run compile
vsce package

Install locally:

code --install-extension custom-background-images-1.0.1.vsix

out/ must be compiled first; src/ is excluded from the published extension via .vscodeignore.

Important notes

Workbench patching

This extension modifies your editor installation’s workbench.html file. That is how backgrounds persist across sessions inside the real workbench DOM.

• Always use Disable & Reload or uninstall the extension to restore the original file.
• The patch is wrapped in a versioned marker so re-apply and uninstall can find and remove it reliably.
• Patching may require administrator privileges on some systems.

Integrity notifications

Because workbench.html is modified, the editor may show an “installation appears to be corrupt” toast. The extension suppresses that specific notification while the patch is active. This is expected behavior for this approach — not an indication that your editor binaries are damaged.

Uninstall

The vscode:uninstall hook runs out/uninstall.js, which calls the same restore logic as Disable. If you remove the extension manually without running uninstall, you may need to restore workbench.html yourself or reinstall the editor.

Recommended workflow

1. Tune settings and use Preview Layout.
2. Apply only when satisfied.
3. Keep opacity low (defaults to 0.15) for readable code.
4. Use blur sparingly on the editor region to avoid distracting from text.

License

Copyright © 2026 Hadi Hajihosseini. Custom Background Images Source License (see LICENSE).

• You may use, modify, and run this project for yourself or your team.
• Contributions are welcome via pull requests to the official repository.
• You may not publish this code (or derivatives) as an extension or plugin for any editor or IDE (VS Code, Cursor, JetBrains, Vim/Neovim, etc.) on any marketplace or registry without permission from the copyright holder.

Feedback

Found a bug or have an idea?

If this project helps you, consider giving it a ⭐ on GitHub.

Custom Background Images — created by Hadi Hajihosseini.
Make your editor feel like yours, without leaving the IDE.