Evolution Executor

A VSCode sidebar extension for running terminal commands from a convenient button palette. Ships with a curated library of common web development commands, and lets you build your own personalized command palette — organized with tags, searchable, and scoped to individual projects or your entire environment.

Developed by james-evolution on GitHub.

Features

Command button palette — click any button to run its associated command in the integrated terminal, with an optional confirmation modal
Built-in command library — pre-loaded with common React, Next.js, Node.js, npm, Git, and Python commands
Command descriptions — hover over any command button to see a plain-English description of what it does; custom commands support an optional description field in their creation form
Custom commands — create your own buttons mapped to any terminal command you choose
Edit commands — right-click any custom command to edit its name, terminal string, description, tags, or scope
Delete with confirmation — remove custom commands via the right-click context menu, with a confirmation prompt before deletion
Scope badges — each custom command displays a 📁 Workspace or 🌐 Global pill badge so you can tell at a glance where it is saved
Tag system — organize commands with color-coded tags; built-in tags have fixed brand colors, custom tags get auto-assigned colors that you can override
Manage Tags — change the background color of any custom tag; badge text color adjusts automatically for legibility
Real-time search — filter commands by name or tag across both tabs
Scope filter tabs — narrow My Commands to All, Local, or Global with a single click
Global vs. local scope — choose whether a custom command is available everywhere or only in a specific workspace
Export and Import — back up any subset of your commands to a JSON file and restore them to any scope, on any machine; re-importing the same file will never create duplicates
Quick Import / Export — Users can specify default JSON files that will be used for one-click importing / exporting of custom commands lists.
Settings — toggle the run confirmation modal on or off, and access Manage Tags, via the gear icon in the header
Theme-aware UI — the sidebar adapts automatically to any VSCode light, dark, or high-contrast theme, the theme can also be changed to a small list of presets

Getting Started

Open the Evolution Executor panel from the activity bar (sidebar icon)
Browse the Default Commands tab to find and run common commands instantly
Switch to My Commands to create your own

The Two Tabs

Default Commands

Contains the full built-in command library, organized across six categories:

Category	Tag	Commands included
React / Vite	`react`	Scaffold app, dev server, build, preview, install deps
Next.js	`next`	Scaffold app, dev server, build, production server, lint
Node.js Backend	`node`	Init project, install Express / CORS / dotenv / Nodemon, run server
General npm	`npm`	Install, update, outdated, cache clean, clean reinstall (Mac/Linux + Windows)
Git	`git`	Init, clone, status, add, commit, push/pull/fetch, branches, merge, log, diff, stash, reset, revert, remotes, tags
Python	`python`	Create/activate/deactivate venv, pip management, requirements.txt workflows, pytest, Black, Flake8
vsce	`vsce`	Install CLI, login, preview files, package, publish (plain, patch, minor, major)

Default commands are read-only — they cannot be deleted or modified. Hovering over any default command shows a description of what it does.

My Commands

Your personal command palette. Supports creating, editing, searching, deleting, exporting, and importing custom commands. Scope filter tabs and a search bar sit above the list — see Searching and Filtering for details.

Running Commands

Click any command button to run it. By default, a confirmation modal appears before the command is sent to the terminal. The modal displays the command's name and the exact terminal string that will be executed, so you always know what you're about to run.

To disable the confirmation step, open Settings and uncheck Confirm before running commands.

A terminal named EvolutionExecutor is created automatically on first use and reused across subsequent clicks. If you close it manually, a new one is created the next time you run a command. The command is sent exactly as written — no modification, no shell wrapping.

Settings

Click the ⚙ icon in the top-right corner of the sidebar to open the settings panel.

Setting	Default	Description
Confirm before running commands	On	Shows a modal with the command name and terminal string before executing. Disable for instant one-click execution.
Theme	VSCode (Auto)	Controls the color scheme of the sidebar. See Themes below.

Settings are stored globally and persist across all workspaces and VSCode restarts.

When the My Commands tab is active, the settings panel also shows a Manage Tags button for quick access to the tag color editor. See Manage Tags.

Creating Custom Commands

Click + Add Command on the My Commands tab to open the creation form.

Fields

Name (required) The label shown on the command button. Keep it short and descriptive. Example: Start dev server

Command (required) The exact terminal command to execute when the button is clicked. Example: npm run dev -- --port 4000

Description (optional) A plain-English explanation of what the command does. Shown as a tooltip when hovering over the button. Useful for commands whose purpose isn't immediately obvious from the name alone. Example: Starts the dev server on port 4000 with hot reload

Tags (optional) A comma-separated list of tags to categorize the command. Tags are displayed as color-coded badges on the button and can be used to filter commands via the search bar. Example: react, vite, dev

Tags are normalized to lowercase automatically. You can reuse built-in tags (like react or node) to match their fixed brand colors, or invent your own. See Tag Color System for details on how tag colors work and how to customize them.

Scope (required) Determines where the command appears. See Command Scope below.

Command Scope

When creating a custom command, you choose between two scopes:

Global

The command is saved to your VSCode user profile and appears in the My Commands tab across all workspaces and projects. Use this for commands you reach for regardless of what you're working on.

Examples of good global commands:

git log --oneline -20
npm cache clean --force
code . (open current folder in new window)

Local

The command is saved to the current workspace and appears in My Commands only when that workspace is open. Use this for project-specific commands that would only make sense in a particular codebase.

Examples of good local commands:

docker-compose up -d (project has its own compose file)
npm run test:e2e (end-to-end tests specific to this project)
A custom deploy script path unique to this repo

Note: The Local scope option is disabled when no workspace folder is open in VSCode. In that case, all new commands will be saved as Global.

How Commands Are Stored

Custom commands are stored using VSCode's built-in state APIs — no files are written to your workspace or home directory, and nothing is committed to git.

Scope	Storage API	Where the data lives
Global	`globalState`	VSCode's user profile directory on your machine
Local	`workspaceState`	VSCode's internal workspace storage, keyed to the workspace URI

Both storage locations are:

Per-user — not shared with other OS users or other VSCode installations
Persistent — survive window reloads, VSCode restarts, and extension updates
Safe — never written to your project folder, never at risk of being committed to version control

Settings Sync

VSCode has a built-in feature called Settings Sync that lets you back up your editor configuration to a Microsoft or GitHub account and automatically restore it when you sign in on another machine. This covers things like your theme, keybindings, and extensions — and Evolution Executor participates in it.

The following data is included in Settings Sync:

Global commands — your custom commands saved with global scope
Settings — the run confirmation toggle
Tag colors — any custom colors you've applied to tags

This means if you sign in to VSCode on a new computer with the same account, your global commands and preferences will appear automatically without any manual export or import step.

Local commands are not synced. They are intentionally kept on the machine and workspace they were created in, since they typically reference project-specific paths, scripts, or tools that only exist in that environment.

If you haven't set up Settings Sync, your data still saves locally as normal — sync is simply an optional feature built into VSCode. You can enable it from the VSCode accounts menu in the bottom-left corner of the editor.

Data Persistence and Loss

Uninstalling and reinstalling the extension

Uninstalling Evolution Executor through the VSCode Extensions panel does not delete your commands or settings. The data is stored in VSCode's internal profile directory on your machine, which is separate from the extension installation itself. When you reinstall the extension, everything comes back exactly as you left it.

When data is lost

Situation	Data lost?
Uninstall → reinstall (standard)	No
VSCode window reload or restart	No
Extension update	No
Uninstalling with an explicit "Clear Extension Data" option	Yes
Deleting or resetting your VSCode user profile	Yes
Moving to a different machine without Settings Sync enabled	Yes — global data stays on the original machine
Signing in to a different account on Settings Sync	Yes — synced data follows the account

Editing and Deleting Custom Commands

Right-click any custom command in the My Commands tab to open a context menu with two options:

Edit — opens the edit form pre-filled with that command's current values
Delete — prompts a confirmation modal before permanently removing the command

Editing

You can change any field:

Name — the label shown on the button
Command — the terminal string that runs when clicked
Description — the tooltip shown on hover (leave blank to fall back to the raw command)
Tags — the comma-separated tag list
Scope — switching between global and local moves the command to the appropriate storage automatically

Click Save Changes to apply, or Cancel to discard.

Deleting

Selecting Delete from the context menu opens a confirmation modal showing the command name. You must confirm before the command is permanently removed.

Default commands cannot be edited or deleted.

Exporting and Importing Commands

Evolution Executor can export your custom commands to a JSON file and import them back — useful for backing up your work, sharing a command set with a colleague, or migrating commands to a new machine.

Accessing Export / Import

In the My Commands list view, click the Export/Import button (beside + Add Command) to open a two-option prompt. Select Export or Import to begin the respective flow.

Exporting

The export flow walks you through three choices:

Scope — choose whether to export your Local or Global commands
Quantity — choose All (exports every command in that scope) or Select (shows a checklist so you can pick individual commands)
Save location — a standard save dialog lets you choose where to write the file

The output is a human-readable JSON array. Each entry contains the command's name, terminal string, tags, scope label, and creation timestamp:

[
  {
    "name": "Start dev server",
    "command": "npm run dev",
    "description": "Starts the Vite development server with hot module replacement",
    "tags": ["react", "node"],
    "scope": "global",
    "createdAt": 1708000000000
  },
  {
    "name": "Run E2E tests",
    "command": "npx playwright test",
    "tags": ["testing"],
    "scope": "local",
    "createdAt": 1708100000000
  }
]

Note: Internal identifiers (id, isDefault) are stripped from the export — they are regenerated fresh on import and would not be meaningful on another machine.

Importing

Click Export/Import → Import
Choose a target scope — Local (saves to the current workspace) or Global (saves to your user profile, available everywhere)
Select a previously exported .json file via the open dialog

Each command in the file is validated before import. Entries missing a name or command field are skipped silently. All imported commands receive fresh IDs on import.

Duplicate prevention — if an entry's name and command both match a command that already exists in the target scope, that entry is skipped. This means importing the same file multiple times is always safe and will never create duplicates.

The scope field recorded in the file is informational only — it is always overridden by the scope you select at import time. This means you can freely import a set of global commands as local ones (or vice versa) without editing the file.

The description field is optional in the JSON. If present, it is preserved on import and shown as the hover tooltip on the command button.

If the selected file is not a valid JSON array, an error message is shown in the sidebar and no commands are modified.

Searching and Filtering

Text search

Both tabs have a filter bar at the top. Type any text to narrow the visible command list in real time.

A command is shown if:

Its name contains the search text (case-insensitive), or
Any of its tags contain the search text

For example, searching react will show all commands tagged with react. Searching dev will show commands with "dev" in their name (like "Start React Dev Server") or in their tags.

The filter is cleared automatically when switching between tabs.

Scope filter tabs (My Commands)

At the top of the My Commands list, three scope tabs let you narrow the view without typing anything:

Tab	Shows
All	Every custom command (global + local combined)
Local	Only commands saved to the current workspace
Global	Only commands available across all workspaces

The text search bar works within whichever tab is active — so selecting Global and then searching deploy shows only global commands whose name or tags match "deploy". Switching tabs resets the scope filter to All.

Tag Color System

Tags are displayed as colored badges on each command button.

Built-in tag colors

The four built-in tag colors are fixed and cannot be changed:

Tag	Color
`react`	Cyan `#149eca`
`next`	Charcoal `#4a4a4a`
`node`	Green `#417e38`
`npm`	Red `#cc3534`

Custom tag colors

Any tag not in the table above is initially assigned a color deterministically — the same tag string always produces the same color, across sessions and across users. Colors are chosen from a curated palette designed to be readable on both light and dark VSCode themes.

You can override any custom tag's color using Manage Tags.

Manage Tags

Click the ⚙ gear icon while on the My Commands tab, then click Manage Tags to open the tag color editor.

The panel lists every custom tag that appears on at least one of your commands (built-in tags like react and node are excluded — their colors are fixed). For each tag you'll see:

A live badge preview showing the tag's current color
A color picker (🎨) — click it to open your system's color picker and choose any background color
A Reset button — appears only when you've applied a custom color; clicking it reverts the tag back to its auto-assigned color

Badge text color (white or black) is adjusted automatically based on the chosen background color to ensure legibility.

Custom tag colors are stored globally and apply across all workspaces.

Themes

The sidebar UI uses VSCode's built-in CSS theme variables, so it automatically adapts to whichever VSCode theme you have installed. On top of that, Evolution Executor ships with four built-in palette options, selectable from the Settings panel.

Theme	Description
VSCode (Auto)	Default. Inherits your active VSCode theme — buttons, inputs, and backgrounds all match the rest of the editor automatically.
Evolution (Dark)	A custom dark palette derived from the Evolution brand: deep navy backgrounds, green accents, and purple highlights.
Evolution (Vampire)	A high-contrast dark palette with near-black backgrounds and deep blood-red accents.
Evolution (Luna)	A moonlit night sky palette with deep blue-slate backgrounds, cool silver text, steel-blue accents, and a soft icy-blue glow on hovered elements.

The selected theme is stored globally and persists across workspaces and VSCode restarts. If you use VSCode Settings Sync, your theme preference syncs across machines along with your other settings.

Attribution

Sidebar coding icon created by Ralf Schmitzer - Flaticon