Visual Studio Code Setup And Use

Visual Studio Code, usually called VS Code, is an application for reading and editing text and code. Its integrated terminal is a terminal panel inside the editor; the shell and computer used there depend on whether the VS Code window is local or connected to a remote system.

Goal: open the correct project, use its declared tools and Python environment, and distinguish local work from an Euler Remote-SSH session.

Prerequisites: start the local Passport first. Complete the Git, Python, AI, or Euler prerequisite mission before using the corresponding VS Code feature.

New to text commands? Read how to open a terminal and run one command before using a command block. It explains the labels used below and what to copy.

Execution context: VS Code runs on your own computer unless the lower-left status bar explicitly names a remote SSH host. Commands run in the integrated terminal shown by the current window.

Use this guide when a Passport mission or project asks you to work in VS Code. Installing VS Code does not install Git, Python, Conda, an AI service, or Euler access. Complete those Passport missions in the order assigned.

1. Install VS Code#

Where: your computer.

1. Open https://code.visualstudio.com/download.
2. Choose the installer for your operating system and processor.
3. Run the installer from the official download.
4. On Windows, enable Add to PATH when the installer offers it.
5. Open VS Code and select Help > About.

Expected: the About window names Visual Studio Code and shows a version.

If an ETH-managed computer blocks installation, stop and request the approved software installation. Do not bypass device management or use an unknown download mirror.

2. Open The Exact Project Folder#

1. In VS Code, select File > Open Folder.
2. Select the repository folder named by the Passport or project README.
3. Select Terminal > New Terminal.
4. Run:

git rev-parse --show-toplevel
git status --short --branch

Expected: the first command prints the folder you intended to open. The second prints the expected branch and no unexplained changes.

If Git says the folder is not a repository, or the path is not the expected project, close the VS Code window and open the correct folder. Do not initialize a new repository inside a clone.

3. Check Where The Terminal Runs#

Before copying a command, read both:

• the lower-left VS Code status bar;
• the terminal prompt and current path.

A local window runs commands on your computer. A window marked SSH runs commands on the remote host. The mission always names the required machine and shell. Do not run a PowerShell command at an Euler Bash prompt, or an Euler command on your laptop.

4. Install Only Required Extensions#

Open Extensions with Ctrl+Shift+X on Windows/Linux or Command+Shift+X on macOS. Search by name, check the publisher, and install only what the project or current mission requires.

An extension can read or modify workspace files. Do not install an extension only because a pop-up recommends it.

Python Extension Before Interpreter Selection#

Where: the local VS Code window with the Passport practice folder open. Use the exact folder path shown by Prepare practice folder, not .transport. The Conda environment and interpreter must already pass the Python mission's terminal checks. This extension does not install that interpreter for you.

1. Open Extensions with Ctrl+Shift+X on Windows/Linux or Command+Shift+X on macOS.
2. Search @id:ms-python.python. Choose Python by Microsoft, not an extension with a similar name.
3. Select Install if missing. If it is installed but disabled, use the extension's Manage menu to enable it for this workspace.
4. Save open files and reload the VS Code window if prompted. Keep the separate terminal running the Passport open.
5. Open workspace/python_project/passport_example.py from the Explorer. Open the Command Palette and find Python: Select Interpreter.

Expected: Python by Microsoft is installed and enabled in this window, and its interpreter-selection command is available. You are ready to select an existing interpreter; you do not need Python: Create Environment.

If the command is missing, recheck the extension ID, its enabled status in this workspace, and that this is your local project window. Save and reload if VS Code requests it, then reopen the .py file.

If the window says Restricted Mode, Python features may be unavailable even with the extension installed. Use Manage in that banner or select the Restricted Mode badge to review the exact folder. Trust only the recognized Passport practice folder after reviewing its contents. Keep unfamiliar folders restricted and ask for help if uncertain. Do not trust a parent directory or disable Workspace Trust globally to clear this error. See VS Code's Workspace Trust guide.

If device policy blocks the extension or enabling it, ask IT for the approved installation. Do not bypass policy or reinstall Python to repair an editor command. You can continue in the already verified command terminal without using VS Code's Python features.

5. Select The Project Python Environment#

Complete the terminal checks in Create A Reproducible Python Environment and the extension setup above first. Then:

1. Open the Command Palette with Ctrl+Shift+P or Command+Shift+P.
2. Run Python: Select Interpreter.
3. Select the exact Python executable printed by the mission's Verify the active interpreter step, inside this repository's .venv folder.
4. Select Terminal > New Terminal. Return to the practice folder and repeat the mission's Activate the project environment step in that terminal.
5. Run:

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version

Expected: the editor selection, sys.executable and pip path refer to the same project .venv. For this Passport exercise, Python must report 3.11. An integrated terminal that was already open can still use an older selection; verify the new terminal instead of assuming the status bar changed it.

If the interpreter is not listed, keep the working environment. Recheck that you opened the practice root, open the interpreter picker again and use its path-entry option if available to enter the exact executable printed by the terminal check. If that option is unavailable or the path is rejected, use the verified terminal and ask for setup help. Do not select base, recreate .venv, or install another Python merely to populate the picker.

For a notebook, use its kernel picker and select that same environment. Do not choose Conda base, a global Python, or an environment from another project.

6. Run The Project's Own Check#

Read README.md, CONTRIBUTING.md, and pyproject.toml when present. Run the smallest test or check that the repository documents. Examples such as pytest, Ruff, or a build command are valid only when the repository actually declares them.

Record the command and its real result. A green editor decoration is not a substitute for the documented terminal check.

7. Use Git Without Hiding The State#

Complete the manual Git and pull-request missions before relying on VS Code's Source Control buttons. The required sequence remains:

git status --short --branch
git diff
git add <reviewed-path>
git diff --cached
git commit -m "type(scope): concise summary"
git push

This block shows the order; it is not a copy-paste command. Replace <reviewed-path>, the commit type, scope, and summary with the values from your current task. The Git workflow explains branches, Conventional Commits, draft pull requests, and safe recovery.

After completing that workflow once, you may use the Source Control panel for the same operations. Always inspect Changes before staging and Staged Changes before committing. Do not press Sync, Pull, Force Push, or Merge to clear an error you do not understand.

8. Add AI Only After The Manual Baseline#

Complete the manual pull-request mission first, then follow the assigned AI tool setup. The supported no-cost student route is VS Code with GitHub Copilot Student. Zed with a personal OpenRouter account is optional and may cost money.

Before accepting an agent change:

1. state the task and files it may touch;
2. prohibit secrets, protected data, unapproved dependencies, and publishing;
3. inspect commands before approval;
4. inspect git diff yourself;
5. run the repository's check yourself.

An agent does not prove that a command succeeded by saying that it ran it.

9. Use Euler Remote-SSH Only After Terminal Access Works#

Do not debug VS Code and SSH at the same time.

1. Complete Establish Safe Euler SSH Access until the key-only alias prints config-ok.
2. If a compute-node editor is required, complete the Euler tunnel procedure until its terminal-only test succeeds.
3. Install Remote - SSH from Microsoft.
4. Run Remote-SSH: Connect to Host and select euler-tunnel.
5. Enter the local SSH-key passphrase if prompted. Do not expect an ETH password during the key-only connection.
6. After the remote window opens, run:

hostname
printf 'SLURM_JOB_ID=%s\n' "$SLURM_JOB_ID"

Expected: the hostname is an allocated compute node and SLURM_JOB_ID is not empty. A first connection may install VS Code Server under ~/.vscode-server; this is expected.

If the terminal-only SSH or tunnel test fails, close VS Code and repair that test first. Stopping euler-tunnel releases its allocation.

Finish A Work Session#

1. Save intended files.
2. Run the project's verification command.
3. Run git status --short --branch and account for every listed path.
4. Push only reviewed commits when the project workflow requires it.
5. Close remote VS Code windows and stop temporary Euler tunnels or jobs.

Common Failures#

• Wrong folder: reopen the repository root printed by the Passport.
• Wrong machine: close the remote window or connect to the named host, then recheck the status bar and prompt.
• Wrong Python: activate/reselect the project .venv, open a new terminal, and print sys.executable again.
• Git buttons disabled: verify that git status works in the opened folder.
• Unexpected files: stop, inspect git diff, and do not stage them.
• Agent makes broad edits: stop the agent, inspect the diff, and discard only changes you have identified as unwanted.
• Remote-SSH asks for an ETH password: close VS Code and rerun the exact key-only terminal test from the SSH mission.

Verification#

• VS Code opens the intended repository root.
• The status bar and terminal identify the intended machine.
• The selected Python and pip belong to the project environment when relevant.
• The documented project check passes in the integrated terminal.
• Git shows only intended changes.
• AI and Remote-SSH were configured only after their prerequisite missions.

Ask For Help When#

The required extension cannot be installed on a managed computer, the project instructions and selected interpreter disagree, the window connects to the wrong remote host, or recovery could discard unexplained Git changes. Share the VS Code version, operating system, named failed step, and error text after removing credentials, personal information, private paths, and research data. Never share a credential or private key.

Python extension installation and interpreter selection checked on 2026-09-20 against the official Python tutorial, extension management and Python environment guide. Other sections retain their existing review dates.

Verified: 2026-09-05. Review by: 2026-12-05. Owner: lab software maintainer.