Run Package (Universal Runner)
A professional, JetBrains-style persistent run/debug configuration toolbar for Visual Studio Code. This extension adds a single, global workspace toolbar to your VS Code status bar that allows you to manage, select, and run customized terminal processes and multi-command packs (parallel or sequential) with one click.
Features
- JetBrains-style Status Bar Toolbar: Adds a dropdown configuration selector (showing the currently selected config) and a single Play (▶) button on the right side of the status bar.
- Dynamic Play / Stop (■) Controls: The Play button switches to a Stop icon when the selected configuration is running. Clicking Stop terminates only the terminals linked to that configuration.
- Config Storage & JSON Schema: Stores configurations inside
.vscode/universal-runner.json with autocomplete and validation via a built-in JSON schema.
- Single Commands & Packs:
- Single Commands: Runs custom shell command string with optional
cwd, env variables, terminal icon, and terminal theme color.
- Command Packs: Groups multiple single commands to launch them in their own separate terminals.
- Parallel or Sequential Modes:
- Parallel (Default): Spawns all commands simultaneously.
- Sequential: Runs commands one after another. Waits for each command to resolve with a successful exit code
0 before starting the next. Stops and alerts on failures.
- Automatic Lifecycle Management: Re-running a command automatically terminates its previous active terminal session to avoid clutter.
- Interactive Configuration Manager: Add, edit, and delete commands/packs using a keyboard-navigable QuickPick UI flow.
- Workspace State Persistence: Remembers your last selected configuration across VS Code reloads.
Configuration File Example
Configurations are stored in .vscode/universal-runner.json. Here is an example of what it looks like:
{
"commands": [
{
"id": "backend",
"name": "Run Backend",
"command": "npm run dev",
"cwd": "server",
"env": {
"PORT": "3000"
},
"icon": "server",
"color": "terminal.ansiGreen"
},
{
"id": "frontend",
"name": "Run Frontend",
"command": "npm run start",
"cwd": "client",
"icon": "play",
"color": "terminal.ansiBlue"
},
{
"id": "test",
"name": "Run Tests",
"command": "npm run test",
"icon": "beaker",
"color": "terminal.ansiYellow"
}
],
"packs": [
{
"id": "full-stack",
"name": "Full Stack Dev",
"mode": "parallel",
"commandIds": ["backend", "frontend"]
},
{
"id": "build-pipeline",
"name": "Production Build & Test Pipeline",
"mode": "sequential",
"commandIds": ["test", "frontend"]
}
]
}
How to Use
- Click on the status bar item showing $(list-flat) Select Config or run the command
Run Package: Manage Configurations via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
- Add commands and packs using the interactive flow.
- Select your active configuration from the status bar dropdown.
- Click the Play (▶) button on the status bar next to it to launch the command(s).
- Click the Stop (■) button to terminate the active configuration.
Additionally, the toolbar icons are contributed directly to the editor title menu (the top-right toolbar of open editor tabs, matching Code Runner's layout). You can select configurations and trigger Run/Stop actions directly from the editor header!
Schema Configuration Options
Each single command has the following settings:
id: Unique alphanumeric ID.name: Display name.command: Shell command string.cwd (Optional): Working directory relative to the workspace root.env (Optional): Object containing environment key-value pairs (e.g. "PORT": "8080").icon (Optional): Icon name like terminal, server, play, beaker, gear, debug, database, cloud.color (Optional): Terminal theme color like terminal.ansiBlack, terminal.ansiRed, terminal.ansiGreen, terminal.ansiYellow, terminal.ansiBlue, terminal.ansiMagenta, terminal.ansiCyan, terminal.ansiWhite.
Enjoy quick, organized project runners!
