Pinned Paths

Pinned Paths keeps selected local files and folders in the VS Code Explorer without adding them to the active workspace. The view uses the native Explorer tree presentation and persists selections globally by default.

Local use

Install dependencies and build the extension from this directory:

npm install
npm run compile

Press F5 from VS Code to open an Extension Development Host. The Pinned Paths view appears in the Explorer sidebar. VS Code controls the initial placement of contributed views, so move it within the sidebar if needed.

The first activation adds these paths when they exist:

• ~/.claude
• ~/.codex
• ~/Documents/notes
• ~/Documents/screenshots
• ~/Desktop

Initialization runs once. Removing a seeded path is permanent unless it is added again explicitly. Paths that do not exist are skipped.

Working with selected paths

Use the view title actions or the Explorer context menu to add files and folders. Selected roots can be browsed with the normal file tree interaction. Pinned Paths also supports:

• Global and workspace-specific persistence scopes
• Native Shift-click and Command-click multiple selection on macOS
• Per-root ascending or descending alphabetical order with directories first
• Dotfiles and dot-directories shown alongside other folder contents
• Drag reordering and Move Up or Move Down commands
• Root aliases and relative-path labels
• Direct file and folder creation, filesystem rename, and Trash deletion
• Copying absolute and workspace-relative paths
• Opening files to the side and folders in a new window
• Revealing items in the operating system file manager
• Opening or reusing an integrated terminal for a folder
• Searching within a selected folder
• Automatic refresh and optional active-file reveal

Folder rows expose distinct New File and New Folder icons, so every creation has an explicit target directory. Press Enter with exactly one selected filesystem entry to rename it. Empty or multiple selections leave the filesystem unchanged, and the shortcut stays inactive while text input has focus.

On macOS, Option+Cmd+C copies the context item's absolute path or every absolute path in the current Pinned Paths selection. Multiple paths use one line each. The command is safe when nothing is selected.

The Pinned Paths: Scope setting defaults to global. Use workspace when selected paths should belong only to the current workspace.

Pinned Paths: Auto Reveal defaults to off so editor activity does not move or expand the pinned tree. Enable it when opening a file should select that file in Pinned Paths and expand its ancestor folders.

Right-click a pinned root folder and choose Sort Ascending or Sort Descending. The direction persists with that root and applies to every nested folder without changing the order of the pinned roots themselves.

Workspace presets

A workspace can define named root sets in .pinned-paths.json. Applying a preset replaces the current workspace-scope roots. Missing paths and paths that resolve outside the first workspace folder are ignored. Pinned Paths never rewrites the preset file. Reapplying a preset preserves the saved direction of each canonical root path that remains selected.

{
  "presets": [
    {
      "name": "Service",
      "paths": [
        "src",
        "tests",
        { "path": "docs/runbooks", "alias": "Runbooks" }
      ]
    }
  ]
}

Preset paths are relative to the first workspace folder. Switch to Workspace scope before applying a preset.

Runtime ownership

Activation constructs one owner for each runtime concern. PinnedRoots keeps global and workspace root snapshots, persists mutations, and emits one change event after a successful change. The tree provider renders those snapshots and owns native tree interaction, opt-in active-file reveal, and filesystem watchers.

PinnedPathActions performs dialogs, filesystem mutations, clipboard writes, terminal access, search, and open commands. WorkspacePresets owns preset file interaction and its watcher. Command registration targets those concrete owners directly, so the tree provider does not become a second command API.

Development checks

Run the sandbox-runnable check during development:

npm run check

It covers formatting, TypeScript, lint, unit tests, package inventory, and dependency audit. Before sharing a build, run npm run check:full, which adds the Extension Host tests that need a graphical process boundary. Build a VSIX without installing it with:

npm run package