Path Navigator

Path Navigator is a VS Code extension for finding files and directories by their workspace-relative paths.

Features

• Find files and directories by partial names, fuzzy matches, or workspace-relative paths.
• Match camelCase and separator abbreviations such as psc for pathSearchCatalog.ts.
• Jump directly to nested directories with path chains such as bcd/cde.
• Search complete paths with the // prefix, for example //src/comp/button.
• Navigate directories from the keyboard with Tab and Shift+Tab.
• Open files in editor tabs or reveal directories in the built-in Explorer.
• Prioritize recent, frequent, pinned, and previously selected results.
• Open directly at a line and column with inputs such as main.ts:42:7.
• Filter file and directory results directly from the picker.
• Keep the active result stable while navigating large result lists.
• Stay up to date as workspace files and directories change.
• Respect VS Code workspace exclusions and .gitignore files.
• Work across multi-root workspaces, Remote SSH, Dev Containers, WSL, Codespaces, and virtual workspaces.
• Customize shortcuts, result display, search behavior, exclusions, and performance limits.

Usage

1. Run Path Navigator: Open File or Reveal Directory from the Command Palette.
2. Alternatively press Cmd+Alt+P on macOS or Ctrl+Alt+P on Windows/Linux.
3. With an empty input, the picker shows the direct children of the current directory. Type part of a name to search all descendants in the current scope. Both ab and bc can match a directory named abc.
4. Press Tab to complete the active result. Completing abc changes the input to abc/ and shows only its immediate files and subdirectories.
5. Continue typing and pressing Tab to navigate the path one level at a time.
6. Press Enter on a file to open it. By default, Enter on a directory reveals it in Explorer; set pathNavigator.directoryAction to enter to navigate into it.

Global search and directory navigation work together. Given abc/bcd/cde/file.ts, typing fi or ile at the workspace root finds the file immediately. After completing abc/ with Tab, the same search only returns matches located somewhere inside abc/.

Multi-segment input also works as a directory-chain shortcut. If the workspace contains abc/bcd/cde/file.ts, entering bcd/cde uniquely resolves abc/bcd/cde and immediately shows the direct files and subdirectories under cde. If more than one directory ends in bcd/cde, Path Navigator keeps the matching paths in the candidate list instead of choosing one silently.

Prefix the input with // when slashes should be part of a global full-path query instead of an exact directory scope. For example, //src/comp/button can rank src/components/Button.tsx without completing src/ and components/ first.

When you press Up or Down, Path Navigator freezes the visible result snapshot so background updates do not move the selection unexpectedly. Editing the query, entering a directory, pressing refresh, or reopening the picker resumes result updates.

The status line distinguishes indexing, searching, paused results, search-budget limits, and index-size limits. While results are still allowed to update, the picker also preserves its scroll position and skips updates whose visible ordering has not changed.

For example, the path abc/bcd/cde can be reached as follows:

ab  → Tab → abc/
bc  → Tab → abc/bcd/
cd  → Tab → abc/bcd/cde

The refresh button in the picker rebuilds the path index. You can also run Path Navigator: Refresh Path Index.

The gear button opens the extension settings. Run Path Navigator: Configure Keyboard Shortcuts to open VS Code's native Keyboard Shortcuts editor filtered to Path Navigator commands.

Keyboard shortcuts

All shortcuts are regular VS Code keybindings and can be changed or removed in the Keyboard Shortcuts editor.

With an empty input, Path Navigator shows pinned and recent/frequent paths first, then files beside the active editor, followed by workspace-root entries. Run Path Navigator: Open from Active File Directory when you want the picker to start as an explicitly scoped directory search.

Append :line or :line:column to a file query to place the cursor when the file opens, for example main.ts:42 or main.ts:42:7.

Search and interaction settings

• pathNavigator.showFiles: include files in results (default true).
• pathNavigator.showDirectories: include directories in results (default true).
• pathNavigator.fuzzyMatching: allow non-contiguous fuzzy matches (default true).
• pathNavigator.directoryAction: make Enter reveal a directory or enter it (default reveal; Tab always enters).
• pathNavigator.resultPathDisplay: show the parent, full, or hidden path beside each result (default parent).
• pathNavigator.freezeResultsOnNavigation: freeze the visible result snapshot while navigating (default true).
• pathNavigator.progressiveSearchResults: publish intermediate search snapshots; disabled by default so each bounded search updates candidates atomically.
• pathNavigator.keepOpenOnFocusLost: keep the picker open after focus changes (default false).
• pathNavigator.showStatusPrompt: show search/index status above results (default true).
• pathNavigator.showStatusBar: optionally show indexing state in the VS Code status bar (default false).
• pathNavigator.openFilesInPreview: open files as preview tabs (default false).

Performance settings

• pathNavigator.maxResults: maximum visible results (default 50).
• pathNavigator.maxIndexEntries: maximum retained index size (default 500000, or 0 for unlimited). The picker reports when the limit is reached.
• pathNavigator.indexConcurrency: concurrent directory reads from a shared work queue during indexing (default 12; lower values may suit constrained remote workspaces).
• pathNavigator.adaptiveRemoteConcurrency: ramp remote concurrency toward the configured maximum and back off when latency indicates congestion (default true).
• pathNavigator.autoRefreshIndex: apply incremental file/directory updates (default true).
• pathNavigator.incrementalUpdateBatchLimit: maximum coalesced file events handled incrementally before falling back to a full rebuild (default 2000).
• pathNavigator.initialIndexDepth: initial workspace.fs scan depth (0 means a complete index). Positive values load entered directory subtrees on demand.
• pathNavigator.persistIndex: restore the workspace path index when reopening a workspace (default true).
• pathNavigator.persistentIndexMaxAgeHours: maximum cache age (default 168; 0 accepts any age).
• pathNavigator.refreshPersistentIndexInBackground: reconcile a restored cache with the live workspace in the background (default true).
• pathNavigator.maxSearchCandidates: maximum expanded fuzzy candidates scored per query (default 10000).
• pathNavigator.searchTimeBudgetMs: soft fuzzy-search budget in milliseconds (default 150).
• pathNavigator.recentPathsLimit: workspace-local recent/frequent history limit (default 200, or 0 to disable).
• pathNavigator.queryHistoryLimit: query-to-selected-result history limit (default 500, or 0 to disable).

The histories and persistent index store path metadata only—never file contents. Recent history additionally stores timestamps and open counts; query history stores normalized queries and selection counts. Recent history observes workspace files opened through the normal editor, not only files opened through Path Navigator.

Unambiguous dependency, cache, and framework-generated directories such as node_modules, .venv, __pycache__, .cache, and .svelte-kit are excluded by default. Generic names such as build, dist, out, target, vendor, and coverage remain searchable unless the workspace excludes them. Customize pathNavigator.excludeDirectoryNames when a workspace has other large dependency or generated trees; entries may also be workspace-relative glob patterns. By default, Path Navigator also respects files.exclude, search.exclude, and root or nested .gitignore files. Use pathNavigator.excludeFileExtensions for suffixes such as .log, .map, or .test.ts.

Remote workspaces

Path Navigator supports local folders, Remote SSH, Dev Containers, WSL, Codespaces, and virtual workspaces, including empty directories.

To test a local VSIX, first connect to the remote environment, then run Extensions: Install from VSIX... in that remote window and reload it. Use Developer: Show Running Extensions to confirm that Path Navigator is running in the remote extension host.

Replace Cmd+P

VS Code does not provide an API for adding directories to its built-in Cmd+P results. To use Path Navigator in its place, add the following to your user keybindings.json:

{
  "key": "cmd+p",
  "command": "pathNavigator.open"
}

Use ctrl+p on Windows or Linux. You may also bind the original Quick Open command, workbench.action.quickOpen, to another shortcut.

Development

From the repository root, run:

npm install
npm run check --workspace extensions/path-navigator
npm test --workspace extensions/path-navigator
npm run test:integration --workspace extensions/path-navigator
npm run benchmark --workspace extensions/path-navigator
npm run package:path-navigator
npm test

The integration suite launches an isolated VS Code Extension Host and verifies both a local workspace and a provider-backed remote/virtual workspace through the real workspace.fs API. The package command disables npm dependency discovery because the extension has no runtime dependencies and otherwise vsce can traverse the parent npm workspace.

Press F5 in VS Code to launch an Extension Development Host.

Known limitation

Directory navigation uses VS Code's built-in revealInExplorer command. The command is used by bundled VS Code extensions but is not part of the documented public command API, so compatibility is tested on a best-effort basis.