Skip to content

vscode-usage.md

Latest commit

 

History

History
361 lines (275 loc) · 13.4 KB

vscode-usage.md

File metadata and controls

361 lines (275 loc) · 13.4 KB

Visual Studio Code Usage

Use this guide to set up Visual Studio Code for this dotfiles repository and work effectively with the shared editor profile.

Table of contents

Scope

This guide explains the Visual Studio Code setup and usage model used by this repository:

  • where settings are defined,
  • how extensions are installed,
  • how keybindings and MCP servers are managed,
  • how to verify that your local editor matches the shared profile.

It is written for both new users and existing contributors who want a reliable, repeatable setup.

How to use this guide

  1. Start with Task-first quick start for common tasks.
  2. Complete Configuration once to apply the profile.
  3. Use Operational command reference for day-to-day checks.
  4. Use Troubleshooting if behaviour differs from expected.

Task-first quick start

If you want to... Start with... Why this works
Install VS Code + Insiders on macOS assets/31-install-developer-apps.macos.sh Installs both apps via Homebrew automation.
Install repository-recommended extensions assets/41-configure-developer-tools.macos.sh Reads .vscode/extensions.json and installs each recommendation.
Find where user settings come from assets/vscode/settings.json This is the shared source for user-level settings managed by chezmoi.
Find where workspace settings come from .vscode/settings.json + project.code-workspace Keeps repository-specific behaviour separate from user defaults.
Review keyboard shortcut customisations assets/vscode/keybindings.json Contains grouped, documented shortcut mappings.
Review MCP server configuration assets/vscode/mcp.json Declares configured MCP servers (Context7, Playwright, etc.).
Make source files open in VS Code by default (macOS) assets/42-configure-file-associations.macos.sh Uses duti to map common source file types to VS Code.

How Visual Studio Code is used in this project

This repository treats VS Code as a first-class, reproducible developer tool.

  • App installation is automated on macOS.
  • Extension installation is automated from a committed recommendation list.
  • User settings, keybindings, and MCP servers are centrally defined and applied through chezmoi-managed files.
  • Workspace-specific behaviour is kept in repository .vscode/ files and project.code-workspace.

The goal is predictable formatting, consistent linting behaviour, and less setup friction across machines.

Configuration

Setup

Flow diagram

flowchart TD
  A[Run dotfiles setup] --> B[Install VS Code apps on macOS]
  B --> C[Install recommended extensions from .vscode/extensions.json]
  C --> D[Apply shared user config from assets/vscode]
  D --> E[Open project.code-workspace]
  E --> F[Optional: set file associations with duti]
Loading

Configuration source map

Area Source of truth Purpose
User settings assets/vscode/settings.json Shared editor behaviour, formatting, search excludes, AI/Chat settings.
User keybindings assets/vscode/keybindings.json Shared keyboard shortcuts with grouped sections.
User MCP servers assets/vscode/mcp.json MCP server endpoints and stdio server commands.
VS Code recommendations .vscode/extensions.json Extension recommendations installed by automation script.
Workspace settings .vscode/settings.json Repository-specific chat/workspace overrides.
Workspace file project.code-workspace Folder + file association overrides for dotfiles filenames.
Chezmoi mapping private_dot_config/Code/User/symlink_*.tmpl Maps local Code/User files to shared assets in this repo.

Prerequisites

Before applying this guide, ensure:

  1. You are on macOS for automated app installation scripts.
  2. Homebrew and base dotfiles prerequisites are already installed.
  3. The code CLI is available in your shell PATH.
  4. jq is available (used by extension installation workflow).

Apply

1) Install Visual Studio Code apps

The macOS developer app script installs both stable and Insider builds:

./assets/31-install-developer-apps.macos.sh

Installed app identifiers in that script:

  • visual-studio-code
  • visual-studio-code@insiders

2) Install recommended extensions

Use the developer-tools configuration script:

./assets/41-configure-developer-tools.macos.sh

The config-vscode function reads extension IDs from .vscode/extensions.json and executes code --install-extension for each recommendation.

Manual equivalent:

while IFS= read -r ext; do
  code --install-extension "$ext"
done < <(jq -r '.recommendations[]' .vscode/extensions.json)

3) Apply user settings, keybindings, and MCP servers

The repository manages user-level VS Code files via chezmoi templates:

  • private_dot_config/Code/User/symlink_settings.json.tmpl
  • private_dot_config/Code/User/symlink_keybindings.json.tmpl
  • private_dot_config/Code/User/symlink_mcp.json.tmpl

These map your local VS Code user files to:

  • assets/vscode/settings.json
  • assets/vscode/keybindings.json
  • assets/vscode/mcp.json

4) Open the workspace file

Open the repository workspace to get file association overrides for dotfiles:

code project.code-workspace

5) Configure macOS file associations (optional)

To make common source file types open in VS Code by default:

./assets/42-configure-file-associations.macos.sh

This configures associations for extensions including js, ts, py, sh, yaml, json, toml, md, xml, and css.

Verify

Run these checks after setup:

# Check VS Code CLI
code --version

# Validate JSON/JSONC source files (using jq where JSON-compatible)
jq '.' .vscode/extensions.json > /dev/null && echo "extensions.json valid"
jq '.' project.code-workspace > /dev/null && echo "workspace file valid"
jq '.' assets/vscode/mcp.json > /dev/null && echo "mcp.json valid"

# Show extension recommendation count and first entries
jq -r '.recommendations | length' .vscode/extensions.json
jq -r '.recommendations[:10][]' .vscode/extensions.json

# Confirm selected settings exist
grep -n '"editor.formatOnSave"' assets/vscode/settings.json
grep -n '"workbench.colorTheme"' assets/vscode/settings.json
grep -n '"chat.tools.terminal.sandbox.enabled"' assets/vscode/settings.json

Extension profile

This section summarises the extension strategy. The authoritative source remains .vscode/extensions.json.

Recommended extension inventory

mermaidchart.vscode-mermaid-chart
alefragnani.bookmarks
anthropic.claude-code
charliermarsh.ruff
continue.continue
davidanson.vscode-markdownlint
dbaeumer.vscode-eslint
eamodio.gitlens
editorconfig.editorconfig
esbenp.prettier-vscode
github.copilot-chat
github.copilot
github.github-vscode-theme
github.vscode-github-actions
github.vscode-pull-request-github
golang.go
gruntfuggly.todo-tree
hashicorp.terraform
johnpapa.vscode-peacock
mhutchie.git-graph
ms-azuretools.vscode-docker
ms-kubernetes-tools.vscode-kubernetes-tools
ms-ossdata.vscode-postgresql
ms-playwright.playwright
ms-python.debugpy
ms-python.python
ms-python.vscode-pylance
ms-toolsai.jupyter
ms-vscode-remote.remote-containers
ms-vscode.hexeditor
ms-vscode.live-server
ms-vsliveshare.vsliveshare
ms-windows-ai-studio.windows-ai-studio
openai.chatgpt
redhat.vscode-xml
redhat.vscode-yaml
rust-lang.rust-analyzer
sonarsource.sonarlint-vscode
streetsidesoftware.code-spell-checker-british-english
tamasfe.even-better-toml
tomoki1207.pdf
vscode-icons-team.vscode-icons
wayou.vscode-todo-highlight
yzhang.dictionary-completion
yzhang.markdown-all-in-one

Unwanted recommendation

The repository marks this extension as unwanted:

  • ms-vscode.makefile-tools

Keybindings quick reference

Selected custom shortcuts from assets/vscode/keybindings.json:

Action Shortcut
Font zoom in/out/reset cmd+= / cmd+- / cmd+0
Delete current line shift+enter
Insert line after/before cmd+enter / cmd+shift+enter
Move line up/down alt+up / alt+down
Quick open cmd+e
Editors by MRU cmd+p
Go to symbol cmd+shift+o
Rename symbol f2
Find in files cmd+shift+f
Quick fix cmd+.
Toggle terminal `ctrl+``
Command palette cmd+shift+p
Open settings cmd+,
Open keybindings cmd+k cmd+s
Open extensions view cmd+shift+x

Operational command reference

  • List recommended extensions:

    jq -r '.recommendations[]' .vscode/extensions.json

  • Reinstall all recommended extensions:

    while IFS= read -r ext; do
  code --force --install-extension "$ext"
done < <(jq -r '.recommendations[]' .vscode/extensions.json)

  • Check whether a specific extension is installed:

    code --list-extensions | grep '^github.copilot$'

  • Open this repository workspace:

    code project.code-workspace

  • Run the automation entry points:

    ./assets/31-install-developer-apps.macos.sh
./assets/41-configure-developer-tools.macos.sh
./assets/42-configure-file-associations.macos.sh

Customisation and good practices

  • Keep shared defaults in assets/vscode/* so setup remains reproducible.
  • Keep repository-only behaviour in .vscode/settings.json or project.code-workspace.
  • Prefer adding/removing extension recommendations in .vscode/extensions.json instead of ad-hoc local installs.
  • If you use VS Code terminal heavily, keep in mind this repository intentionally disables Oh My Zsh in VS Code terminal sessions (TERM_PROGRAM=vscode) to avoid known prompt/plugin issues.

Troubleshooting

If extensions are not installed:

  • Ensure code is available in PATH: code --version.
  • Check that .vscode/extensions.json is valid JSON.
  • Re-run ./assets/41-configure-developer-tools.macos.sh with REINSTALL=true.

If settings do not match repository defaults:

  • Check chezmoi-managed mapping files under private_dot_config/Code/User/.
  • Verify source files in assets/vscode/ contain expected values.

If file associations do not apply on macOS:

  • Ensure duti is installed.
  • Ensure /Applications/Visual Studio Code.app exists.
  • Re-run ./assets/42-configure-file-associations.macos.sh.

Further reading