Code Telescope: bringing Telescope's power to VS Code

If you're a Neovim user, you've probably heard of (or use) Telescope.nvim

One of the most powerful tools in the Neovim ecosystem for fuzzy navigation—files, text, symbols, git commits, branches, and more, all in a single interface.

What if you could have that same experience in VS Code?

That's the motivation behind Code Telescope—an extension that brings Telescope's philosophy to Visual Studio Code.

---

🎯 The Problem It Solves

Let's be honest: VS Code already has several ways to search for things:

• Ctrl+P for files
• Ctrl+Shift+F for text
• Ctrl+Shift+O for symbols
• Ctrl+Shift+G for git

But each of these is a different interface, with different behaviors, and different keyboard shortcuts. There's no unified "hub" for searching.

Code Telescope solves this by providing a single interface that abstracts all these functionalities—and more—into a consistent, extensible, and powerful fuzzy finder.

🏗️ Architecture: Extensibility via Decorators

The extension is built on three architectural pillars:

1. Annotation-based adapters — Each finder is registered via decorators
2. Backend/UI separation — Extension host (backend) separate from webview (UI)
3. Type-safe communication — Shared interfaces between layers

┌─────────────────────────────────────────────────────────────┐
│                    Extension Host (Backend)                 │
│  ┌─────────────────┐                                        │
│  │ Finder Providers│                                        │
│  │ @FuzzyFinder()  │                                        │
│  └────────┬────────┘                                        │
│           │                                                 │
│           │                                                 │
│           │                                                 │
│    ┌──────▼────────┐                                        │
│    │ Presentation  │                                        │
│    │     Layer     │                                        │
│    │  - Registry   │                                        │
│    │  - Handlers   │                                        │
│    └──────┬────────┘                                        │
└───────────┼─────────────────────────────────────────────────┘
            │ Message Protocol (type-safe)
┌───────────┼─────────────────────────────────────────────────┐
│    ┌──────▼────────┐           Webview (UI)                 │
│    │   Webview     │                                        │
│    │  Controller   │                                        │
│    └──────┬────────┘                                        │
│           │                                                 │
│           ┼────────────────┐                                │
│           │                │                                │
│     ┌─────▼─────┐  ┌───────▼────────┐                       │
│     │   Data    │  │    Preview     │                       │
│     │  Adapters │  │   Renderers    │                       │
│     └───────────┘  │ @PreviewRender │                       │
│                    │      ()        │                       │
│                    └────────┬───────┘                       │
│                             │                               │
│                    ┌────────▼────────┐                      │
│                    │    Keyboard     │                      │
│                    │    Handlers     │                      │
│                    └─────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

🔌 Finders (Backend)

Finders are data providers registered via @FuzzyFinderAdapter:

@FuzzyFinderAdapter({
  fuzzy: "workspace.files",
})
export class WorkspaceFileProvider implements IFuzzyFinderProvider {
  async querySelectableOptions(): Promise<QueryResult> {
    // Return list of files
  }

  async onSelect(identifier: string): Promise<SelectResult> {
    // Action on selection (open file, navigate, etc.)
  }
}

🔄 Data Adapters (UI)

On the UI side, data adapters transform backend data into displayable options:

export class FileDataAdapter implements IFuzzyFinderDataAdapter {
  parseOptions(data: any): FileOption[] {
    // Convert backend data to UI options
  }

  getDisplayText(option: FileOption): string {
    // Define how the option appears in the list
  }

  filterOption(option: FileOption, query: string): boolean {
    // Custom filtering logic
  }
}

Data adapters are the bridge between raw backend responses and the interactive list shown to users.

🎨 Preview Renderers (UI)

Preview renderers are also on the UI side and transform raw data into visual representations, registered via @PreviewRendererAdapter:

@PreviewRendererAdapter({
  adapter: "preview.codeHighlighted",
})
export class CodeHighlightedPreviewRenderer implements IPreviewRendererAdapter {
  async render(
    previewElement: HTMLElement,
    data: PreviewData,
    theme: string
  ): Promise<void> {
    // Render syntax-highlighted code in the preview pane
  }
}

This keeps the backend clean—it only provides data—while the UI is responsible for how that data looks.
Code Telescope supports any VS Code theme out of the box. The preview uses Shiki as the syntax highlighter, optimized for minimal bundle size by loading only the necessary grammars on-demand. This means syntax highlighting that perfectly matches your current theme—whether you're using Dracula, One Dark Pro, or any custom theme—without bloating the extension.

📦 What's Built-In

The extension ships with a complete suite of finders:

• Workspace files — Fuzzy matching across all files
• Text search — Integrated ripgrep
• Symbols — Functions, classes, variables
• Git branches — Quick branch switching
• Keybindings — Browse VS Code shortcuts
• Recent files — Recently opened files
• Color schemes — Theme switching
• Diagnostics — Errors, warnings, hints
• Tasks — Workspace tasks
• Call hierarchy — Function call relationships

And the best part: all with inline preview and keyboard-only navigation.

🎯 Harpoon: Bookmarking Style

Inspired by ThePrimeagen's Harpoon, I also included a bookmarking system:

• Mark files with Ctrl+Alt+M
• Navigate with Ctrl+1 through Ctrl+9
• View all marks with Ctrl+Alt+H
• Persists per workspace

This allows instant navigation to your most important files—no searching required.

🔧 Extensibility: Creating Your Own Finders

One of the coolest parts: you can create custom finders without touching the extension code.

Just create a .cjs file in .vscode/code-telescope/:

module.exports = {
  fuzzyAdapterType: "custom.example",

  backend: {
    async querySelectableOptions() {
      return { items: ["Item 1", "Item 2"] };
    },

    async onSelect(item) {
      return { data: item, action: "showMessage" };
    }
  },

  ui: {
    dataAdapter: {
      parseOptions(data) {
        return data.items.map((item, i) => ({ id: i, text: item }));
      },
      getDisplayText(option) {
        return option.text;
      },
      filterOption(option, query) {
        return option.text.toLowerCase().includes(query.toLowerCase());
      }
    }
  }
};

The system does the rest—automatic wiring via the type system. You can check an example here

🤔 Why This Architecture?

I chose this design for several reasons:

1. Decoupling — Finders don't know about UI, UI doesn't know about implementation details
2. Testability — Each component can be tested independently
3. Type safety — Compile-time guarantees prevent integration bugs
4. Extensibility — New finders without touching existing code

The decorator-based approach means the registry is built at compile-time, and the message protocol ensures the backend and UI stay in sync.

💡 Inspiration

Obviously, Telescope.nvim by tjdevries (TJ DeVries) was the main inspiration—the fuzzy finder that revolutionized Neovim navigation.

And Harpoon by ThePrimeagen—the bookmarking system that changed how we think about file navigation.

What makes Telescope special isn't just the functionality—it's the extensibility and the unified experience. Code Telescope tries to capture that same essence.

---

If you use VS Code and miss Telescope's power, check it out on the VS Code Marketplace or Open VSX.
Youtube video explaining (It is in portuguese BR, but you can enable automatic translation)

Check code on Github

Feedback and contributions are welcome!