implement shell activation helper commands

[eleanorjboyd]

auto-activation is a setting python-envs.terminal.autoActivationType with 3 options for what it can be set to (as described in the documentation section of this issue)

Right now the command palette command Python Envs: Revert Shell Startup Script Changes exists to remove shell startup from all shells. I want to expand this command to instead be called:

Python Envs: Manage Shell Startup
From there show the menu:
Revert Shell Startup Script Changes
View Shell Startup Statuses
Inject Shell Startup
they do the same:

Revert Shell Startup Script Changes -> this does what already exists

View Shell Startup Statuses -> this will query the shell startup status of each of the shell types and output it in the logs (also open the logs there)

Inject Shell Startup -> takes you to another page which shows you the shells as a list (display a label next to the default shell)

• the user then selects the shell they want to inject the shell startup into
• inject the shell startup

when making menus, make sure to show back buttons and also make sure the person can escape the menu if needed

---

---

Here is some documentation of how Auto-activation works:

Setting: Terminal Auto-Activation Type

Id: python-envs.terminal.autoActivationType

Purpose: Controls how the Python Environments extension activates the selected Python environment when a new terminal is created in VS Code.

When auto-activation is enabled, the extension ensures python, pip, and related tools resolve to the interpreter in your chosen environment without requiring you to run activation commands manually.

---

Modes at a glance

• Command (default)
  Runs the environment’s activation command in the terminal right after it opens.
  Why default? This is the most reliable and easiest to set up across shells because it doesn’t require modifying profile files or registry state.

• Command Shell Startup
  Configures the shell’s startup so activation happens before any commands run (via profile scripts or the Windows autorun registry key for cmd.exe).
  Why choose it? Required when tools (e.g., Tasks or Copilot agentic actions) need the environment to be active before their first command executes.

• Off
  Disables automatic activation entirely.

---

1) Command (default)

How it works

• When you open a new terminal in VS Code, the extension injects and runs the activation command in that terminal session.
• The exact activation command depends on:
  • Your shell type (e.g., Bash, Zsh, PowerShell, Command Prompt)
  • Your OS type (Windows, macOS, Linux)
  • Your environment type (e.g., venv, Conda, Pipenv)
• After the command runs, python resolves to your selected environment.

How to debug Command mode

1. Open a new terminal in VS Code — you should see the activation command injected automatically at the top.
2. Determine the correct activation command by activating your environment manually outside of VS Code (using the correct command for your shell, OS, and environment type).
3. Compare:
   • The command VS Code injected
   • The command that works outside VS Code
4. If they differ:
   • Report the mismatch, or
   • Check additional settings that might influence the environment path (e.g., default interpreter path settings, environment variables).

---

2) Command Shell Startup

How it works

• The extension modifies your shell’s startup configuration so the environment is activated automatically before any commands run.
• Implementation differs by shell:
  • Bash, Zsh, Fish, PowerShell → Adds a snippet to the shell’s profile file.
  • Command Prompt (cmd.exe) → Sets a Windows Registry autorun entry that runs a .bat script on shell start.
• Injected scripts will include comment markers like:

  # >>> vscode python
  # version: 0.1.0
  ...
  # <<< vscode python

• Once set, any terminal of that type opened in VS Code will have the environment active immediately.
• If at any time you want to remove these changes, run Python Envs: Revert Shell Startup Script Changes from the Command Palette.

For full details on how shell startup activation is implemented (including script examples for each shell type), see the Shell Startup Activation section of the README.

Why choose this

• Required for Tasks or Copilot when they run commands in a new terminal and need the environment to be active before the first command executes.

How to debug Shell Startup mode

Bash/Zsh/Fish/PowerShell

1. Open a new terminal in VS Code — the environment should be active immediately.
2. Open your shell’s profile file and confirm the injected snippet is present (look for the comment markers shown below).

   # >>> vscode python
   # version: 0.1.0
   ...
   # <<< vscode python

3. If the snippet is missing, open the shell in VS Code, set the auto-activation type to Command Shell Startup, and reload the window to

Command Prompt

1. Open Registry Editor and navigate to: HKEY_CURRENT_USER\Software\Microsoft\Command Processor
2. Look for the autorun value — it should point to a .bat file used for activation.
3. If missing, open a cmd terminal in VS Code, set the auto-activation type to Command Shell Startup, and reload the window to trigger injection.

---

appendix:

Information to include in a bug report

• Shell type (Bash, Zsh, PowerShell, Command Prompt, Fish)
• OS (Windows/macOS/Linux)
• Environment type (venv, Conda, Pipenv, etc.)
• Auto-Activation Type setting value (Command / Command Shell Startup / Off)
• Expected behavior
• Actual behavior
• If Command mode:
  • Activation command injected by VS Code
  • Activation command that works outside VS Code
• If Command Shell Startup mode:
  • For Bash/Zsh/Fish/PowerShell: Is the snippet with # >>> vscode python present in the profile file?
    • Profile file path
  • For Command Prompt: Is autorun registry value present?
    • Path in autorun value
• Whether the issue happens in only one shell or multiple shells
• Whether it reproduces after Reload Window and opening a fresh terminal