Cleats: Python Launchpad

Run and debug the current or last Python file in VS Code with ease and out-of-the-box support.

Why It Exists

Running and debugging Python files in VSCode quickly is at least inconvenient. Let's fix that.

• Ctrl+Shift+F10 creates a launch configuration for the current script and runs it -- quick and easy.
• Ctrl+F10 runs the last configuration again -- fast re-run.
• Ctrl+Shift+F9 and Ctrl+F9 do the same for debugging -- debug with the same ease.
• Run and debug multiple scripts simultaneously -- no more "A debug session is already active" errors.
• Launchpad manages per-file launch configurations with predictable defaults and settings-based overrides.

Behavior

Usage

1. Open a Python file, be it a python script or a test file.
2. Press Ctrl+Shift+F10 to run it, or Ctrl+Shift+F9 to debug it.
3. Use Ctrl+F10 / Ctrl+F9 to run or debug the last valid Python target, even when editor focus is elsewhere.
4. The first execution of a script opens a dialog to set up the launch configuration.
   • run command template (default is python {script})
   • current working directory (default is the Python workspace folder)
   • select which launch.json to use in multi-root workspaces (default is the target file's workspace folder)
5. Subsequent runs/debugs reuse and preserve existing managed target entries, feel free to edit them.

Commands

• Run Current File
• Debug Current File
• Run Last File
• Debug Last File
• Remove Managed Target Configurations

Default Keybindings

Default shortcuts use Ctrl key combinations on all platforms:

• Debug Current File: Ctrl+Shift+F9
• Run Current File: Ctrl+Shift+F10
• Debug Last File: Ctrl+F9
• Run Last File: Ctrl+F10

Target Resolution

• Depends on the Microsoft Python extension (ms-python.python) for Python debugging support.
• Auto-detects test files by filename (test*.py, *_test.py).
• In test files, Run/Debug Current File resolves the current function or method when the cursor is inside one; otherwise, it targets the whole file.
• Run Last File and Debug Last File are no-ops when no previous target exists.

Run and Debug Execution

• Run/debug commands resolve runtime templates from managed launch env keys (PYTHON_LAUNCHPAD_RUN_COMMAND / PYTHON_LAUNCHPAD_TEST_COMMAND) with safe fallbacks.
• Debug commands choose pytest or unittest based on Python test settings (python.testing.pytestEnabled / python.testing.unittestEnabled).
• Debug Current File and Debug Last File launch by managed configuration name for script targets, so the Run and Debug panel keeps the selected Launchpad target for F5 reuse.
• Run commands mirror the managed configuration environment, so cwd, envFile, and env behave the same as debugging:
  • envFile is loaded first, then inline env entries override it (an env value of null removes the variable).
  • When the managed configuration has no envFile, the Python extension's python.envFile setting is used, exactly as it is for debugging (default ${workspaceFolder}/.env, silently skipped when absent).
  • cwd, envFile, and inline env values resolve ${workspaceFolder}, ${workspaceFolder:name}, ${workspaceFolderBasename}, ${file}, ${fileDirname}, ${fileBasename}, ${fileBasenameNoExtension}, ${fileExtname}, ${relativeFile}, ${relativeFileDirname}, ${userHome}, ${env:NAME}, and ${pathSeparator}.
  • As in VS Code, ${workspaceFolder} is the workspace folder that owns the managed launch.json, while ${workspaceFolder:name} can reference any folder of a multi-root workspace.
  • A configured envFile that cannot be resolved or read reports a warning instead of running with the variables silently missing.
• Prints a terminal summary tail after each run with outcome, exit code, and runtime (green for success, red for failure).

Managed Configuration Rules

• Creates and updates only extension-managed debug configurations.
• Existing managed target configurations are never overwritten once created.
• User-managed launch configurations remain untouched.

Settings

Command template settings:

• cleatsPythonLaunchpad.runCommandTemplate

  • Default: python {script}
  • Used for script targets and written to PYTHON_LAUNCHPAD_RUN_COMMAND when creating a managed target.

• cleatsPythonLaunchpad.testCommandTemplate

  • Default: python -m pytest {testTarget}
  • Used for test targets and written to PYTHON_LAUNCHPAD_TEST_COMMAND when creating a managed target.

• cleatsPythonLaunchpad.generatedLaunchNamePrefix

  • Default: Launchpad

• cleatsPythonLaunchpad.launchJsonPath

  • Default: empty string
  • Optional path that selects which launch.json Cleats manages in multi-root workspaces.
  • Supports absolute file path to launch.json or a folder path (mapped to <folder>/.vscode/launch.json).
  • If empty, Cleats uses the target Python file's workspace folder.

• cleatsPythonLaunchpad.managedTargetConfigurationLimit

  • Default: 20
  • Limits managed Launchpad target entries per workspace-folder launch.json.
  • If creating a new managed target exceeds the limit, the least-recent managed target (first in order) is removed.
  • Existing targets keep their order when run/debugged again.

• cleatsPythonLaunchpad.launchConfigurationTemplate

  • Default: {}
  • JSON object applied as a base override for newly created managed target launch configurations.
  • Use it to define defaults (for example justMyCode, subProcess, env, envFile) without editing managed launch entries manually.

• cleatsPythonLaunchpad.executeDialogEnabled

  • Default: true
  • If true, first execution of an unmanaged target shows a setup dialog before the managed target configuration is created.
  • Dialog customization order: run command template, current working directory, then launch target workspace folder (multi-root only).

• cleatsPythonLaunchpad.runOpenNewTerminalIfBusy

  • Default: true
  • If true, run commands open a new terminal when a previous Cleats run is still active.

• cleatsPythonLaunchpad.debugOpenNewTerminalIfBusy

  • Default: true
  • If true, debug commands can launch an additional debug session when a matching target is already active.

• cleatsPythonLaunchpad.terminalReveal

  • Allowed values: always, silent, never

Release History

0.2.1 (2026-07-25)

• Fixed run commands ignoring envFile when it points at another workspace folder (for example ${workspaceFolder:backend}/.env) while the managed launch.json lives in a different folder; debugging already worked in this case.
• Aligned variable resolution for cwd, envFile, and inline env values on one resolver that also supports ${workspaceFolderBasename}, ${file}, ${fileBasenameNoExtension}, ${fileExtname}, ${relativeFileDirname}, ${userHome}, ${env:NAME}, and ${pathSeparator}.
• Inline env values now resolve launch variables before they reach the run terminal, so entries such as "PYTHONPATH": "${workspaceFolder}/src" no longer leak the literal placeholder.
• Run commands now honor the python.envFile setting (default ${workspaceFolder}/.env) when the managed configuration defines no envFile, matching how the Python debugger resolves it.
• Unresolvable or unreadable envFile values now warn instead of running with the environment silently missing.
• Fixed unittest module targets when cwd differs from the workspace folder; the dotted path is now resolved against the execution directory, with a -k filter fallback when the file sits outside it.
• Reusing an existing managed target no longer rewrites launch.json, which previously reformatted the file on every run or debug.
• Fixed quoting of run command arguments on Windows cmd.exe.

0.2.0 (2026-05-17)

• The first stable release! All core features are now in place.
• Internal refactoring and optimizations.

0.1.5 (2026-05-16)

• Fixed run/debug behavior in multi-root workspaces so Launchpad resolves and launches from the correct target workspace folder.
• Added support for named workspace-folder variables in cwd (for example ${workspaceFolder:project_a}) when running targets.
• Improved default keybinding behavior by skipping Launchpad commands in the integrated shell, ensuring shortcuts execute the extension commands reliably.

0.1.4 (2026-05-14)

• Added setup-dialog support for first-run script execution.
• Improved configuration behavior for managed launch flows.
• Removed legacy behavior to keep execution paths deterministic.

0.1.3 (2026-05-04)

• Added managed template env keys PYTHON_LAUNCHPAD_RUN_COMMAND and PYTHON_LAUNCHPAD_TEST_COMMAND.
• Updated run/debug flows to resolve execution commands from managed target env values with safe fallbacks.
• Standardized command-template behavior for more predictable target execution.

0.1.2 (2026-05-02)

• Consolidated script and test command handling into a unified testCommandTemplate flow.
• Updated run-current and run-last command logic to support the unified template behavior.
• Added debug-busy terminal tracking to improve concurrent debug session handling.

0.1.1 (2026-05-01)

• Added terminal-tail run summaries, including exit code and runtime for every run.
• Added ANSI coloring for terminal-tail summaries (green success, red failure).
• Tightened VSIX packaging to keep publish artifacts runtime-focused.

0.1.0 (2026-04-25)

• Added run/debug commands for current and last Python file targets.
• Established the initial managed launch configuration workflow.