Run Configuration Manager

IntelliJ-style run configurations for VS Code. Save, share, and launch your project's run commands from the Activity Bar — without memorizing terminal flags or digging through scripts.

The extension does the heavy lifting for you. Open the + dialog, pick your project — and the extension scans your codebase, finds your scripts, detects your JDKs, locates your main classes, and pre-fills the form. Most configurations are ready to save in just a few clicks, with no manual research required.

Example — add npm (Angular) Run Config

Example — add Quarkus Run Config

What it does

The extension adds a Run Configurations panel to the Activity Bar. Each entry in the panel represents a saved way to start (or debug) your application. Click once to run, click again to stop. No terminal knowledge required.

Configurations are stored in .vscode/run.json so you can commit them and share them with your whole team. Everyone gets the same one-click experience.

Supported project types

Key features

Auto-detection — Click + and the extension scans your project. Main classes, JDK locations, build tools, profiles, and available scripts are all discovered for you. The form opens instantly and fills in as scanning completes in the background.

Live startup status — The panel shows exactly what your app is doing. Configurations cycle through visual states (Preparing → Starting → Running → Started / Failed) based on real terminal output. You see the actual state of your app, not just whether a process is alive.

One-click debugging — Every configuration that supports it has a Debug button alongside Run. The extension handles attaching the debugger automatically — no separate launch configuration to maintain.

Rich terminal output — The integrated terminal colors log levels, turns file paths and URLs into clickable links, and highlights startup success or failure lines so important output is never buried.

Environment variables and path tokens — Set per-configuration environment variables and use ${workspaceFolder}, ${userHome}, and other tokens anywhere in your configuration. The on-disk file keeps the tokens; the extension resolves them at launch time.

Multi-root workspace support — Works across multi-folder workspaces. Each folder has its own set of configurations. Stop All in the title bar stops every running configuration at once.

Linger mode for crash diagnosis — A per-config "Close terminal as soon as process ends" toggle (default on, matching the original behavior). Switch it off and the integrated terminal stays open after the process exits — Stop button included — so you can scroll back through the logs of a crashed run before dismissing it with any keypress, like VS Code's built-in launcher.

Live command preview — A read-only line at the bottom of the form shows the exact command the extension will execute, including resolved cd <projectPath> prefix, interpreter args, framework invocation, etc. Updates as you edit the form so you can verify before saving.

Shareable configs — Commit .vscode/run.json and your teammates open the same sidebar with the same configured run commands, ready to use. The on-disk format is versioned and migrated forward automatically — older configs work after extension upgrades without manual intervention.

Advanced workflows

Dependency chains

A run configuration can declare other configurations it depends on. When you start the parent, the extension starts each dependency first, waits for it to reach running state, optionally waits a user-set delay, then starts the next step. The whole chain is visible in the sidebar — dependencies render as tree children, and the tree auto-expands during a run so you can see exactly which step is queued, starting, or failed. Cycles are detected at run time.

Set dependencies on any config via the "Depends on" field in the Advanced section of the form. Each entry includes the target (another run config, a VS Code launch config, or a task from tasks.json) plus a delay in seconds. Order matters and is editable via up/down buttons.

Groups

Right-click any configuration and choose Add to Group… to bundle it with others — the picker lets you pick an existing group or create a new one inline. Groups show as folder nodes in the sidebar with their members underneath, and folders can be nested (drag-and-drop a group onto another to nest, drag back to root to flatten).

Right-click a group to:

• Run All Sequentially — starts one member, waits for it to reach running, then the next. Members with their own dependsOn chains still have their dependencies started first. Any member's failure aborts the rest, which stay visible as "skipped" so you can see where it broke. Recurses into sub-folders.
• Run All in Parallel — dispatches every member at once. Recurses into sub-folders.
• Debug All Sequentially / Debug All in Parallel — same flows but routes debuggable configs (Java / Spring Boot / Quarkus / Python / npm) through the debugger automatically, while non-debuggable members fall back to a normal run so the whole group still starts.
• Stop All — terminates every running member, including those in sub-folders.
• Rename / Delete — deleting a group unassigns its members; the configs themselves stay, just ungrouped.

Queued and currently-starting members are overlaid with clock and spinner icons so the pipeline is readable at a glance.

Launch & Tasks integration

A sibling "Launch & Tasks" view surfaces every .vscode/launch.json launch config and workspace task from tasks.json, same tree, hover-to-Run, hover-to-Stop. Launch configs with preLaunchTask / postDebugTask / compound members expand to show the chain; tasks with dependsOn expand recursively.

Clicking a launch or task opens a read-only virtual document showing the JSON plus every dependency inlined — useful for quickly understanding what a compound does without jumping between files.

Debug sessions started from VS Code's own Run & Debug panel also appear as running here, and can be stopped from the same tree.

Docker

Create a Docker run config and the form lists your local containers grouped by running / stopped, sorted running-first. Pick one and the Info panel fills with image, state, created timestamp, port mappings, volumes, and environment — so you can verify you picked the right one before saving. Clicking a docker config in the sidebar opens a live log tail terminal (docker logs -f); the Run / Stop buttons drive the container directly.

Right-click actions

Every config's right-click menu offers type-appropriate shortcuts — no manual mvn / gradle / npm typing:

• Maven configs: Clean · Build (package -DskipTests) · Test, each with the Maven icon.
• Gradle configs: Clean · Build (assemble) · Test, each with the Gradle icon.
• npm configs: Install · Update · Prune.

These shortcuts reuse the config's resolved buildRoot, :module: prefix, and JDK path, so they run against the exact same project state as the main run action. For multi-module Gradle projects that means the right module, not a top-level rebuild.

Dependency-aware build context

Saved configs never assume defaults they can't prove. The "Port" field is populated from the actual project (reads application-<profile>.properties for Spring Boot, quarkus.http.port for Quarkus, package.json scripts or framework convention for npm) — and left blank when nothing could be determined, rather than guessing 8080. Re-runs fire when the profile changes, so picking dev fills in the port from application-dev.properties.

Find Blocking Ports

Click the … menu on the Configurations view → Find Blocking Ports. Opens a searchable, sortable table of every listening port on your machine — port, address, PID, process, protocol — and highlights in green or red any port that matches one of your configurations (green = your config is running on it, red = your config expects it but it's blocked by something else). A Kill button on each row terminates the offending process after confirmation. Built on ss / lsof / netstat depending on platform (Linux / macOS / Windows).

Proactive warnings

When you enable a feature that needs a specific prerequisite in your project, the form surfaces an inline yellow warning with the fix:

• Spring Boot / Tomcat → Rebuild on save: warns when spring-boot-devtools isn't declared in build.gradle / pom.xml (hot reload would silently do nothing without it).
• Spring Boot / Tomcat → Colored log output: warns when a custom logback-spring.xml / logback.xml / log4j2.xml is present — your project's pattern would override the extension's color injection.
• Tomcat → Reloadable context + WAR artifact: warns that reloadable only takes effect for exploded deployments, not packaged WARs.

Warnings are gated on the feature actually being enabled, so the form stays clean until the user opts in.

Python adapter

A first-class Python config type with the same auto-detection ergonomics as the JVM types:

• Five launch modes, each with a focused form:
  • Script — runs python path/to/script.py. Dropdown lists every .py file in the project with if __name__ == "__main__":; user can also type a path or pick a different file via the picker.
  • Module — runs python -m mypkg.cli. Dropdown lists every package containing __main__.py.
  • Framework — runs the framework's own command. Pre-fills launchMode and the command list when a known framework is detected (Django, FastAPI, Flask, uvicorn, gunicorn, Celery, Typer, Starlette, Click).
  • Pytest — runs python -m pytest <args>. Free-form selection field for test paths, -k filters, etc.
  • Custom — anything appended to the interpreter (-c "..." style).
• Interpreter detection — finds project venvs (.venv / venv / env), $VIRTUAL_ENV, version-manager installs (pyenv, asdf, rye, uv, mise, conda), Homebrew + Apple framework Python, system Python, Windows installs. Project venvs win the default-selection race so freshly-opened projects pick the user's venv automatically.
• Framework detection — parses pyproject.toml (PEP 621 + Poetry), requirements*.txt, setup.cfg. Walks up to four parent directories when no metadata exists at the project root (catches monorepo / examples-collection layouts where a single requirements.txt covers many subprojects). Falls back to scanning import statements in *.py if no metadata is found.
• Port auto-fill — picks the right default per framework (flask → 5000, django / fastapi / uvicorn / gunicorn / starlette → 8000) and parses Procfile lines for explicit --port overrides. Switching frameworks in the form re-fills the port if it's still blank.
• One-click debug — wires up debugpy automatically. The interpreter args are hoisted ahead of -m debugpy so user vmArgs (-O, -W default, etc.) take effect; the debug port is threaded consistently between attach and launch so non-default ports work. If debugpy isn't installed in the chosen interpreter, the run surfaces a clear error with the exact pip install debugpy command.
• Pip proxy info — the Advanced section shows the effective pip proxy (pip config list merged with HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars) so corporate-proxied runs are debuggable. Re-evaluates when the user picks a different interpreter.

Node version management

The npm / Node config gains an interpreter selector and a built-in installer dialog:

• Detection of every Node install on the box: nvm, volta, asdf, fnm, n, Homebrew, system Node, the extension's own install root.
• PATH prepend at launch — selecting a Node install prepends its bin/ to PATH so npm / yarn / pnpm and any binary they spawn (Node itself included) come from that install. Standard convention used by every Node version manager.
• nvm-aware installer — clicking the cloud icon next to the Node field on Linux / macOS routes through nvm install <version> instead of downloading a standalone tarball, so the new install lands in the user's existing ~/.nvm/versions/node/ pool. Live nvm output streams into the dialog. On Windows (or any host without nvm), the dialog falls back to downloading the standalone tarball from nodejs.org, verifies SHA-256, extracts to ~/.rcm/nodes/.

Live status detection

The "Started" signal in the sidebar is driven by per-runtime regex patterns matching the canonical "ready" log line for each framework:

• Spring Boot: Started <App> in N seconds, Tomcat started on port: …, Netty/Jetty/Undertow variants.
• Quarkus: Listening on: http://…, Profile dev activated. Live Coding activated.
• Tomcat: Server startup in [N] milliseconds.
• npm dev servers: Angular CLI, Vite, webpack-dev-server, Next.js, Express, plus a generic listening on port N fallback.
• Python: Flask's * Running on http://…, Django's Starting development server at …, Uvicorn running on http://… / Application startup complete., gunicorn's Listening at: http://…, Celery's celery@host ready.

Failure patterns are equally specific — Spring Boot's APPLICATION FAILED TO START, port-bind errors (EADDRINUSE, Address already in use), Python tracebacks / ModuleNotFoundError, gunicorn worker errors, Maven/Gradle BUILD FAIL*, etc. — so the tree flips to red the moment a startup goes wrong, instead of waiting for the process to die.

Stale-config detection

Configurations saved against an older version of the extension get flagged in the sidebar with a warning icon when a detection improvement would now produce different values. The tooltip explains what changed and suggests re-creating — no silent breakage when you upgrade.

Getting started

1. Click the Run Configurations icon in the Activity Bar.
2. Click + to add a configuration — the extension auto-detects your project type.
3. Review the pre-filled form and click Save.
4. Press the play button next to your new configuration to run it.

That's it. Edit or delete configurations at any time from the same panel.