Nameplate

Nameplate is a free VS Code extension that shows the project's name at the left end of the status bar and gives every project a status bar color of its own, so you can tell your VS Code windows apart at a glance. It also works in Cursor, Windsurf, Antigravity, Kiro, Positron and VSCodium.

Why

If you keep several projects open, you have several VS Code windows that look exactly alike: same theme, same layout, same panels. After a few switches it is easy to lose track of which project is in front of you. Then a command runs in the wrong terminal, a commit goes to the wrong repository, or you spend ten minutes editing the wrong copy of a project.

The window title does name the folder, but it is small and easy to skip. A colored status bar can be recognized without reading anything, including on windows that are not focused, and the name next to it tells you what the color stands for.

What it does

• Finds a name for each project, using the folder, the workspace file, package.json, Expo's app.json, pyproject.toml, Cargo.toml, go.mod, pubspec.yaml, composer.json or the Git remote.
• Colors the whole status bar. The color is derived from the Git remote, so a repository gets the same color on every machine. The text on it is white or black, whichever is easier to read.
• Keeps open windows apart. When two windows would get colors that look alike, one of them takes another color.
• Keeps the colors out of Git. VS Code reads a window's colors from .vscode/settings.json, and Nameplate makes sure Git never sees those lines.
• Opens a menu when you click the name, where you can rename the project, pick a color, add a label such as PROD, copy the path or remote, or open the repository.

There is nothing to configure. After installing, every open window shows its name and color.

Windows opened together	Clicking the name

Editors

Nameplate uses only the standard extension API, so it runs in VS Code and in editors built on VS Code 1.85 or later.

Any of them can also install the .vsix from the releases page (Extensions view, then Install from VSIX…). Remote windows over SSH, WSL and Dev Containers work as well, with one exception described under Limitations.

Names

The first of these that gives a meaningful name is used:

1. A name you set with Rename Project.
2. The .code-workspace file name, for saved workspaces.
3. The folder name, unless it is generic (app, src, frontend, tmp.x1 and so on).
4. A product name from Expo's app.json, or displayName / productName from package.json.
5. A package name from package.json, pyproject.toml, Cargo.toml, go.mod, pubspec.yaml or composer.json.
6. The repository and folder name together, for a generically named folder inside a repository.
7. The repository name from the Git remote, then the name of the repository folder.

If another source spells the same name with mixed case, that spelling is used, so a folder called brightdesk with a remote called BrightDesk shows as BrightDesk. Plain lowercase names are shown in capitals with spaces between the words (brightdesk-mobile becomes BRIGHTDESK MOBILE). nameplate.textTransform changes this, and nameplate.nameSource makes another source win.

Colors

The automatic palette has eleven modern colors: blue, indigo, purple, magenta, pink, orange, lime, green, teal, cyan and ocean. They were designed in the OKLCH color space so that every one of them looks clearly different from all the others, with readable text on each. Red, yellow and slate are available when you pick a color yourself; red and yellow are never assigned automatically, because a red or yellow status bar looks like an error or a warning.

Each project gets a fixed order of these colors, worked out from its Git remote (or its folder, if there is no remote). It takes the first color in that order unless that color looks too much like the color of another open window. Colors are compared the way people see them (distance in the OKLab color space), so two shades that look nearly the same count as the same color even when their hex codes differ. Once a project has a color it keeps it.

Windows that start at the same moment, for example right after installing, take turns through a small shared file in Nameplate's storage folder, so each one sees the colors the others picked. If two open windows ever end up looking alike, the one that got the color later switches to a free color and says so in its status bar. Colors you picked yourself never change.

Since all eleven automatic colors are clearly different from each other, up to eleven open windows can be told apart. With more windows open, Nameplate picks the color that differs most from the ones already on screen.

Keeping colors out of Git

VS Code can only color a single window through that project's workspace settings, which live in .vscode/settings.json. Nameplate writes three entries there (statusBar.background, statusBar.foreground and statusBar.inactiveBackground) and keeps them out of Git:

• If the file does not exist yet, Nameplate creates it and adds it to .git/info/exclude. That file is local to your clone and never committed.
• If the file is committed, Nameplate adds a small Git clean filter for it in .git/config and .git/info/attributes, which are local as well. When Git reads the file, the filter removes Nameplate's lines. git status, git diff and commits only see your own changes, and pull, checkout, stash and rebase keep working. The filter runs on the copy of Node that ships with VS Code, so there is nothing to install.
• When Nameplate stops coloring a project, it removes its lines, the exclude entry and the filter again.

To write the colors without hiding them, for example to share a color with your team, set nameplate.keepColorsOutOfGit to false.

Your other settings

Nameplate changes only its own keys inside workbench.colorCustomizations. Other entries stay as they are and keep their order. Before writing a key it remembers the previous value, and turning coloring off puts that value back. If a key is already set by you or another extension (Peacock, for example), Nameplate leaves the window alone and shows the reason in the tooltip. It replaces such a value only when you choose a color yourself, and keeps a copy to restore later.

Commands

All commands are in the Command Palette under Nameplate. Most are also in the menu that opens when you click the project name.

Settings

The defaults are meant to work without changes.

Privacy

Nameplate makes no network requests and collects no data. It reads a few files at the root of your project (package.json and similar, .git/HEAD, .git/config) and writes its color settings into the workspace settings. Custom names and colors are kept in VS Code's storage on your computer. To keep windows apart it keeps a small file (registry.json in its storage folder) with each project's identity, name and colors and the process IDs of the windows that show them. In repositories it colors it adds the local Git entries described above and .git/nameplate-colors.json, which tells the filter which lines are Nameplate's. Remote URLs are shown and copied without credentials.

Limitations

• Colors have to be stored in the workspace settings, because VS Code has no other way to color a single window.
• In remote windows (SSH, WSL, containers) Git runs on the other machine, where Nameplate cannot add its filter. A settings file that is already committed then keeps the default color unless you pick a color yourself.
• Uninstalling cannot clean up projects that are not open. Run Nameplate: Disable in your open windows first. Anything left behind is harmless: without the extension, the filter passes files through unchanged.
• Git applications that cannot run shell scripts don't apply the filter. Git on macOS, Linux and Windows, VS Code and GitHub Desktop all run filters.
• High-contrast themes get the same colors. The text keeps a 4.5:1 contrast ratio, but not the 7:1 those themes aim for.
• VS Code rewrites the workbench.colorCustomizations block when it changes it, so comments inside that block are lost.

Development

npm install
npm run check              # typecheck, lint, formatting, unit tests
npm run test:integration   # runs the extension in a downloaded copy of VS Code
npm run test:multiwindow   # opens six windows of a separate VS Code and checks their colors
npm run package            # builds nameplate-<version>.vsix
npm run media              # rebuilds the product page in docs/ and the GIFs above from site/source.html (needs Chrome)

Press F5 in VS Code to start an Extension Development Host. The code is split into a part without VS Code dependencies (src/core, covered by unit tests) and the code that talks to VS Code. docs/ARCHITECTURE.md explains how the parts fit together.

To install a local build:

code --install-extension nameplate-0.3.0.vsix

Questions

How can I tell VS Code windows apart? Give every project its own status bar color and show its name. Nameplate does both automatically. It reads the project name from the folder, package.json or the Git remote, and gives each project a color that looks different from the other open windows.

How do I change the status bar color for one project? VS Code reads workbench.colorCustomizations from the project's .vscode/settings.json and applies it to that window only. Nameplate writes the status bar colors there for you, picks a readable text color, and lets you choose another color by clicking the project name.

Will it change files in my Git repository? The colors have to be in .vscode/settings.json, but Git never sees them. A settings file Nameplate creates is listed in .git/info/exclude, and in a settings file you commit, a local Git filter hides Nameplate's lines. Nothing shows up in git status or in a commit.

Does it work in Cursor, Windsurf, Antigravity or Kiro? Yes. Nameplate uses the standard extension API. Cursor, Windsurf, Antigravity, Kiro, Positron and VSCodium install it from Open VSX, and VS Code installs it from the Visual Studio Marketplace.

How is it different from Peacock? Peacock colors the title bar, activity bar and status bar with colors you choose and stores them in the workspace settings. Nameplate picks colors automatically, adds the project name, keeps open windows from sharing a color, and keeps the settings out of Git. You can use both; Nameplate leaves colors set by Peacock alone.

Does it collect any data? No. Nameplate makes no network requests and has no telemetry. Everything it stores stays in VS Code's storage on your computer.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md first, in particular the note about the automatic palette, whose order must not change.

Roadmap

• Show the custom name in the window title.
• Optionally color the title bar or activity bar as well.
• A project switcher that lists recent projects with their colors.
• NAMEPLATE_PROJECT and NAMEPLATE_COLOR variables for terminal prompts.
• Team colors stored in committed settings, for projects that want them.

License

MIT