A Telescope-inspired fuzzy finder for VS Code, bringing the power and flexibility of Neovim's Telescope to Visual Studio Code.

Telescope.nvim transformed navigation in Neovim with its extensible, keyboard-first fuzzy finder architecture. Code Telescope brings that same philosophy to VS Code — a single, powerful interface for navigating your entire project.

Find files instantly, search across your workspace, explore symbols, browse git branches and commits — all from one unified, consistent experience.

+------------------------------------------------------------------+
|                     Extension Host (Backend)                     |
|                                                                  |
|   +---------------------------------------------------------+    |
|   |                    Finder Providers                     |    |
|   |                  @FuzzyFinderAdapter                    |    |
|   +---------------------------+-----------------------------+    |
|                               |                                  |
|   +---------------------------v-----------------------------+    |
|   |                  Presentation Layer                     |    |
|   |        WebviewController · Message Handlers             |    |
|   |              Registry Dispatch · HTML                   |    |
|   +---------------------------+-----------------------------+    |
+-------------------------------|----------------------------------+
                                |
                   +------------v------------+
                   |    Message Protocol     |
                   |   (Type-safe interface) |
                   +------------+------------+
                                |
+-------------------------------|----------------------------------+
|                               |            Webview (UI)          |
|   +---------------------------v-----------------------------+    |
|   |                  Presentation Layer                     |    |
|   |      WebviewController · Keyboard · Event Handling      |    |
|   +--------------+------------------------+-----------------+    |
|                  |                        |                      |
|   +--------------v----------+  +----------v------------------+   |
|   |      Data Adapters      |  |      Renderer Adapters      |   |
|   |      parse · filter     |  |       display previews      |   |
|   +-------------------------+  +-----------------------------+   |
+------------------------------------------------------------------+

The architecture is built on three core principles:

1. Annotation-based adapters — finders and renderers are registered via decorators, no manual wiring
2. Clear separation — backend (extension host) and UI (webview) communicate only through a typed message protocol
3. Type-safe communication — shared interfaces prevent integration bugs at compile time

Finders are data providers registered via @FuzzyFinderAdapter. Each finder queries data, provides previews, and handles selection.

@FuzzyFinderAdapter({
  fuzzy: "workspace.files",
  previewRenderer: "preview.buffer",
})
export class WorkspaceFileProvider implements IFuzzyFinderProvider {
  async querySelectableOptions(): Promise<any> { ... }
  async getPreviewData(identifier: string): Promise<PreviewData> { ... }
  async onSelect(identifier: string): Promise<void> { ... }
}

UI-side adapters transform backend data into options and control how each item is rendered in the list.

export class FileDataAdapter implements IFuzzyFinderDataAdapter {
  parseOptions(data: any): FileOption[] { ... }
  getSearchText(option: FileOption): string { ... }
  getHtmlWrapper(option: FileOption, highlighted: string): string { ... }
  getSelectionValue(option: FileOption): string { ... }
}

Registered via @PreviewRendererAdapter, renderers transform raw preview data into visual output inside the preview panel.

The input panel supports Vim-style navigation. Press Ctrl+[ or Esc to enter Normal mode.

Finders can opt into dynamic search, where queries are sent to the backend for server-side filtering — useful for large datasets like workspace text search.

export class WorkspaceTextSearchProvider implements IFuzzyFinderProvider {
  supportsDynamicSearch = true;
  async searchOnDynamicMode(query: string): Promise<any> { ... }
}

Configure via codeTelescope.matching.algorithm:

Uses ripgrep when available (bundled with VS Code or in PATH), with automatic fallback to JavaScript regex-based search.

Quick file bookmarking and navigation inspired by ThePrimeagen's Harpoon for Neovim.

• Index-based navigation — jump to any marked file with Ctrl+1 through Ctrl+9
• Persistent storage — marks are saved to disk per workspace, survive SSH reconnections and reloads
• Position memory — remembers cursor position in each marked file
• Fuzzy finder interface — browse and manage marks with full search support
• Vim-style reordering — cut and paste marks directly inside the finder

Inside the Harpoon finder:

Custom finders are .cjs files placed in .vscode/code-telescope/ and loaded automatically.

.vscode/code-telescope/my-finder.finder.cjs

Complete working examples are available in the examples/ directory.

• CommonJS format only (.cjs)
• Runs in extension host — no browser APIs
• No access to extension internal state

Third-party VS Code extensions can register finders programmatically via the Code Telescope API. See backend/integration/api/README.md for the full API reference, including registerFinder, openFinder, hasFinder, and unregisterFinder.

Inspired by telescope.nvim 🔭

Found a bug or have a feature request? Please open an issue.