Universal Project Runner

Universal Project Runner is a small extension for VS Code-compatible editors, including VS Code, Cursor, Antigravity, and other editors that support the VS Code extension API.

It gives you separate actions for editor run, editor debug, and named terminal commands. Terminal commands are project-based instead of file-based, so they run from the workspace folder or from the command-specific working directory you configure.

Features

• Show a Run Project action that starts the editor's run-without-debugging flow.
• Show a Debug Project action that starts the editor's debugging flow.
• Show a Run Command action when at least one named command is configured.
• Support multiple named project commands in one workspace.
• Show a command dropdown when more than one command is configured.
• Run a single configured command directly without a picker.
• Run an optional preCommand before the main command in the same terminal.
• Give each command its own cwd.
• Show a Stop Project action while a custom command or editor debug/run session is active.
• Hide run, debug, and command actions while a custom command or editor debug/run session is active.
• Use the same actions from the Command Palette.
• Control run and debug actions independently with boolean settings.
• Keep custom commands empty by default, so no extra command action appears until you need one.
• Configure named commands from the editor with Universal Project Runner: Configure Run Command.
• Save command settings per workspace, so different projects can use different commands.
• Reuse terminals for command runs.
• Customize the base terminal name.
• Control bottom status bar run/debug buttons separately.

Why Universal Project Runner?

Many run buttons are tied to the active file. That works for scripts, but it is not ideal for real projects where you may want one-click editor run/debug actions plus project commands like npm run dev, python -m uvicorn main:app --reload, docker compose up, or separate frontend/backend commands.

Universal Project Runner keeps those actions separate, so you can show only the buttons that make sense for each workspace.

Commands

UI Buttons

Universal Project Runner adds two ways to run your project without opening the Command Palette:

The editor title toolbar button appears near the top-right editor actions. VS Code-compatible editors generally do not allow extensions to place arbitrary custom buttons directly in the main app title bar, so this is the closest native top-area location.

Default Behavior

By default, Universal Project Runner enables the editor run and debug actions:

{
  "universalProjectRunner.action.run": true,
  "universalProjectRunner.action.debug": true,
  "universalProjectRunner.commands": [],
  "universalProjectRunner.statusBar.showRun": true,
  "universalProjectRunner.statusBar.showDebug": false
}

By default, only the run action appears in the bottom status bar. The debug action still appears in the editor title toolbar when enabled.

Because universalProjectRunner.commands is empty by default, the custom command button is hidden until you add at least one command. With one command, the editor title toolbar runs it directly. With two or more commands, the editor title toolbar shows a dropdown action that lets you choose the command name.

How It Works

For run and debug actions, Universal Project Runner delegates to the editor's built-in run/debug commands. It also listens for compatible debug/run sessions started outside Universal Project Runner, such as from the menu, keyboard shortcuts, or the Run and Debug panel.

Important: Run/debug actions use the editor's built-in project launch configuration. If your project does not have one yet, create .vscode/launch.json once from the Run and Debug view, then Universal Project Runner can reuse it through the run and debug actions.

Use Run Project and Debug Project when your project works with the default framework launch setup. Use named commands when your project needs custom run commands, environment variables, ports, subfolders, Docker commands, or separate frontend/backend processes.

For custom command actions:

1. Universal Project Runner finds the current workspace folder.
2. It reads universalProjectRunner.commands.
3. It runs the only command directly, or shows a command picker when multiple commands exist.
4. It resolves the selected command's cwd.
5. It opens or reuses a terminal for that workspace command.
6. It waits briefly when a new terminal is created so editor-managed shell setup can finish.
7. It sends preCommand first when configured.
8. It sends the selected command text to that terminal.

If you have multiple workspace folders open, Universal Project Runner uses the folder for the active editor when possible. If it cannot infer the folder, the editor asks you to choose one.

Extension Settings

Command Items

Each item in universalProjectRunner.commands supports:

Example Configurations

Add these to your workspace .vscode/settings.json, or use Universal Project Runner: Configure Run Command from the Command Palette.

Node.js or React

{
  "universalProjectRunner.commands": [
    {
      "name": "Dev Server",
      "cwd": "",
      "command": "npm run dev"
    }
  ]
}

FastAPI

{
  "universalProjectRunner.commands": [
    {
      "name": "FastAPI",
      "cwd": "",
      "preCommand": "source .venv/bin/activate",
      "command": "python -m uvicorn main:app --reload"
    }
  ]
}

Docker Compose

{
  "universalProjectRunner.commands": [
    {
      "name": "Docker Compose",
      "cwd": "",
      "command": "docker compose up"
    }
  ]
}

Frontend and Backend in One Workspace

{
  "universalProjectRunner.commands": [
    {
      "name": "Frontend",
      "cwd": "frontend",
      "command": "npm run dev"
    },
    {
      "name": "Backend",
      "cwd": "backend",
      "command": "python -m uvicorn main:app --reload"
    }
  ]
}

Show Both Run and Debug Buttons

{
  "universalProjectRunner.action.run": true,
  "universalProjectRunner.action.debug": true,
  "universalProjectRunner.statusBar.showRun": true,
  "universalProjectRunner.statusBar.showDebug": true
}

Hide Debug Button

{
  "universalProjectRunner.action.debug": false
}

Hide Run Button

{
  "universalProjectRunner.action.run": false
}

Migrating from Project Runner Settings

Version 0.2.0 replaces the old projectRunner.* settings with universalProjectRunner.* settings.

Old single-command settings are no longer used:

{
  "projectRunner.cwd": "backend",
  "projectRunner.action.command": "npm run dev"
}

Use named commands instead:

{
  "universalProjectRunner.commands": [
    {
      "name": "Backend",
      "cwd": "backend",
      "command": "npm run dev"
    }
  ]
}

Roadmap

• Better custom command lifecycle detection.
• Sidebar view for project actions.

Release Notes

0.2.0

• Renamed settings from projectRunner.* to universalProjectRunner.*.
• Replaced the old single command setting with universalProjectRunner.commands.
• Added multiple named terminal commands with per-command working directories.
• Added a command dropdown when multiple commands are configured.

0.0.1

Initial Project Runner release with:

• Editor run and debug action buttons.
• Optional custom terminal command button.
• Command Palette actions.
• Bottom status bar buttons.
• Editor title toolbar buttons.
• Workspace-aware command execution.