Skip to Content
PluginsBackground Tone (suite)

Background Tone

Background Tone is a Cursor and VS Code extension that tints the side bar, title bar and more per repo, and shows a repo logo (a card at the top of the Explorer and in Source Control, an Explorer item, the tab icon of its settings page, an optional emoji in the window title). With several windows open you can tell which repo is which.

The Repo Identity card also shows the repo’s stack version (the one in versions.json, kept by pnpm ver) in small text beside the repo name. The Repo Settings page groups its cards in three tabs: Color (palette, intensity, areas to tint, preview), Logo (the logo and where it shows) and Actions.

It is the first extension of the pulpfixer suite: the extensions that go with pf, installed and kept current by the system plugin.

PackageShipsWhat
@pulpfixer/ext-bg-toneon its own, never pinned by coreOne bg-tone.vsix (extension id local.bg-tone)
@pulpfixer/preset-suiteon its own, never pinned by corepreset.json listing the extension packages of the suite

Install and update

pf sys apply suite # install the suite extensions Cursor lacks, update older ones pf sys diff suite # show what would change pf sys update # update only the suite extensions already installed (--check, --dry-run) pf update # does the same as a step ("Cursor extensions") pf rp # offers the install for a repo that is set up for pf

pf fetches the latest @pulpfixer/preset-suite and each extension package it lists from the registry into ~/.pf/sys/presets, compares the version in the package with what cursor --list-extensions --show-versions reports, and runs cursor --install-extension <file>.vsix --force. A newer installed version is left alone. pf update never installs a missing extension (that is pf sys apply suite or the question in pf rp), it only updates the ones you have. Reload the Cursor window afterwards.

Settings live in the repo

The extension writes its settings to the bgTone section of the repo’s pulpfixer.json, so they are committed and everyone who opens the repo gets the same tone and logo:

{ "id": "my-repo-1a2b3c4d", "bgTone": { "color": "#3b82f6", "strength": 0.08, "surfaces": ["sideBar", "titleBar"], "logo": "assets/logo.svg" } }

Keys: enabled, color, strength (0 to 0.3), surfaces, baseColors, accentBorder, logo, logoLocations (identityCard, explorerItem, scmCard for the Repo Identity card in Source Control, windowTitle), titleEmoji, palette. The picker, the Repo Settings page (gear icon in the Explorer header) and the commands all write there, keeping every other key and the file’s indentation. A pulpfixer.json that is not valid JSON is never overwritten. A repo that has not been converted yet and only has a pf.json is edited in place.

The Repo Identity card appears once the repo has a logo or a tone color, and also in any repo that has a pulpfixer.json (what pf rp creates), even with no color or logo yet: it then shows the repo name (with a letter in place of the logo) and the action buttons.

A repo that still keeps bgTone.* values in .vscode/settings.json keeps working: they are read until the first change moves them into pulpfixer.json. bgTone.showLastAgent (the last Cursor chats on the identity card) is personal, so it stays a normal VS Code user setting.

The colors the extension derives from these values (workbench.colorCustomizations, an optional window.title) are written to the workspace’s .vscode/settings.json, as before. They are recomputed from pulpfixer.json on every machine, so there is nothing to commit there.

Action buttons

Beside the repo name (right of it, the name shortens to make room), the Repo Identity card shows a row of small icon buttons for the repo’s featured actions: push (pf gp), deploy, publish, docs and your own commands. Hover a button for its name; a click runs pf <action> in the integrated terminal (a terminal named pf: <action>, reused when it is idle, shown instead of typed into when the action is still running).

The list comes from pf actions --json, so only what the repo really has appears. Choose which are featured, and their icons, in pulpfixer.json:

{ "commands": { "seed": { "run": "./scripts/seed.sh", "description": "Seed the database", "icon": "database", "featured": true } }, "actions": { "doc": { "featured": false } } }

The pencil at the end of the row opens the Actions tab of Repo Settings, which lists every action pf offers in the repo (what its menu runs) with a checkbox each; the ticked ones become buttons. The command Background Tone: Choose Featured Repo Actions… does the same from a picker. Both run pf actions feature and unfeature, so pf writes the file. In the pulpfixer checkout itself, cycle (pf c, the dev cycle) is an action too, featured in its pulpfixer.json along with doc. Icons are codicon  names; the font ships inside the extension.

SettingDefault
bgTone.showActionstrueShow the buttons (a personal setting)
bgTone.pfPathpfThe pf command. Set a full path when the editor cannot find it. Machine scope, so a repo cannot change it

Safety: the page only sends an action id; the extension looks it up in pf’s list, runs the executable from bgTone.pfPath and quotes every argument. Nothing runs in an untrusted workspace. Without pf, or with a pf that has no actions command, the card shows a hint instead of buttons, and so does a pf that fails to run (the reason is shown). An editor started from the Dock or Spotlight has a short PATH without node, which pf needs; the extension adds the usual install folders (Homebrew, /usr/local/bin, Volta, ~/.local/bin, npm global) and, if node is still missing, your login shell’s PATH. The list refreshes when pulpfixer.json, package.json, composer.json, a Makefile or a justfile changes.

pf repo

pf rp sets bgTone.logo when it is empty, from the best image it finds (logo.*, icon.* or favicon.* at the root or in assets, public, static, media, images, docs and similar, then the first local image in the README). It skips ignored files and node_modules, accepts only png, svg, jpg, jpeg, webp, gif and ico inside the repo, and never replaces a logo you set. See Tools and repo setup.

Developing it

packages/ext-bg-tone has two manifests: package.json is the npm package (its version is the one pnpm ver bumps) and extension/package.json is the VS Code manifest. pnpm --filter @pulpfixer/ext-bg-tone package builds bg-tone.vsix, stamping the npm version into the extension manifest. The npm package’s pf.extension block ({ "id", "vsix" }) tells pf sys which extension the file is and which file to install; the file name must be plain, inside the package.

Change the extension, then pnpm ver bump packages/ext-bg-tone minor and publish. Core is not bumped along. The next pf update installs the new version into Cursor. A new suite extension is another packages/ext-<name> package with a pf.extension block, listed in packages/preset-suite/preset.json packages and in ORDER in scripts/release.mjs.

Last updated on