Sub-Second Code Search: Building an Indexing Plugin with Cursor + Codex

Why Large Repositories Need a Dedicated Code Search Plugin

In large code repositories with hundreds of thousands of files, the pain points of traditional search tools are glaringly obvious: every query scans the disk from scratch, forcing you to wait several seconds or even longer. For developers who frequently need to locate function implementations and trace call chains, this accumulated latency can seriously slow down the development rhythm.

The fundamental tension here lies in the choice of search approach. Traditional tools like grep use a sequential scanning strategy—traversing every file character by character, with time complexity growing linearly with the number of files. This is acceptable for small to medium projects, but when a repository balloons to hundreds of thousands of files, each query effectively means reading the entire codebase again, making disk I/O an unavoidable bottleneck.

To solve this problem, the author leveraged the Cursor + Codex AI-assisted programming combo to build a code search plugin from scratch. The core idea is: trade space for time—by building a full-text index in advance, most of the query overhead is shifted to the index-building phase, enabling subsequent queries to respond in sub-second, or even millisecond, timeframes.

According to the author's demo, in an enormous repository indexing 236,000 class files and 145,000 source files, a typical query returned results in just 5 milliseconds. Compared to traditional full-disk scanning, this figure represents an order-of-magnitude improvement.

Underlying Technology: Lucene Indexing + BM25 Ranking

Indexing and Ranking Mechanisms

This plugin is built on top of mature full-text retrieval technology. The author mentions using a Lucene-like inverted index structure and adopting the BM25 algorithm for relevance ranking.

To understand why such tools are so fast, the key lies in how inverted indexes work. Traditional sequential scanning requires traversing each file one by one, while inverted indexing does the opposite: it scans all documents in advance and builds a mapping table of "term → list of documents containing that term." When a user searches for a word, the system simply looks it up in the table to retrieve all matching documents, without ever touching the raw files on disk. Lucene is an open-source full-text retrieval library under the Apache Foundation, and it serves as the underlying core of well-known search engines like Elasticsearch and Solr. Refined over more than two decades, it has accumulated a wealth of mature solutions for tokenization, index compression, incremental updates, and more. By choosing a "Lucene-like" structure, the author stands on the shoulders of this mature technology system, bringing industrial-grade search engine capabilities down to the local code retrieval scenario.

BM25 is a classic ranking function in the field of information retrieval, capable of comprehensively evaluating the match between documents and queries based on factors like term frequency and document length—far closer to developers' real needs than simple keyword counting. BM25 (Best Matching 25) originated from probabilistic retrieval model research in the 1990s and remains the default ranking baseline for many search systems today. Its core idea is to evaluate relevance across three dimensions: term frequency (the more a word appears in a document, the more relevant it is, but with a saturation cap), inverse document frequency (rarer words are more distinctive), and document length normalization (to prevent long documents from gaining an advantage simply by containing more words). In contrast, simple keyword counting introduces obvious bias into code retrieval—for example, a utility class with thousands of lines might be mistakenly ranked at the top just because a keyword appears frequently. BM25 balances this well through length normalization, ensuring that function definitions and core implementations truly aligned with the query intent rank higher.

When the index is first built, it performs full-text analysis across the entire repository. While this process has some cost, common queries afterward can usually return within 2 seconds, and hot queries can even reach millisecond-level speeds.

Searching While Indexing

One noteworthy design point is that you don't have to wait for the index to be fully built before you can start searching. The plugin supports querying while building the index on disk, and after files change, it performs incremental updates rather than a full rebuild. This design greatly reduces the initial onboarding wait time for large repositories and makes index maintenance lightweight.

The idea of incremental updates is very common in industrial-grade search systems: the system only needs to re-index the small number of files that have changed, rather than rebuilding the entire index table. For scenarios like code repositories, where daily changes are concentrated and the vast majority of files remain stable, incremental updates keep maintenance costs extremely low while keeping the index always in sync with the latest code on disk.

Rich Code Query Capabilities

The plugin offers a fairly complete combination of query syntax, covering developers' diverse retrieval scenarios:

• Phrase matching, fuzzy matching, loose matching: adapting to different precision needs
• Wildcard support: handling uncertain naming
• Extension / file / directory / time filtering: freely combinable to quickly narrow the scope

In terms of interaction experience, the plugin adopts a streaming loading strategy: large result sets first display the first batch of hits, then progressively stream in subsequent results, avoiding long periods of staring at a blank screen.

In addition, there are several detailed designs that improve efficiency:

• Multiple tabs and locking: keep multiple search contexts for easy comparison
• Alt + equals sign: directly search the currently selected code snippet
• Shift to quickly open files, and switch between indexed header files and source files
• For grep-style and other scenarios, you can directly open the corresponding type

Core Highlight: A Read-Only Index Service for AI Agents

Index Sharing and Write Takeover

The plugin supports multiple instances sharing the same primary index: one process is responsible for writing, while another has read-only access; when the writer shuts down, the reader can automatically take over the writing duties. This mechanism allows the IDE plugin and other tools to work together, avoiding the resource waste of building duplicate indexes.

This "single-writer, multiple-reader" architecture is a classic pattern in databases and distributed systems, with the core goal of maximizing concurrent read capability while ensuring data consistency. For large repository indexes that easily occupy several GB of space and take minutes to build, letting multiple tools share the same index rather than each rebuilding their own saves not only disk space but also precious build time and CPU resources.

ACP Read-Only Service and AI Collaboration

The most critical capability of this upgrade is the ACP read-only service designed for AI programming Agents. It allows AI (such as an assistant integrated into the editor) to directly list and search code, read index snapshots, insert context, or locate call sources.

ACP (Agent Client Protocol) is a recently emerging category of standardized protocols aimed at AI Agents, sharing the same lineage of thinking as MCP (Model Context Protocol) launched by Anthropic—both aim to enable large models to invoke external tools and data sources in a unified, structured way. Before such protocols existed, integrating capabilities like code search and file reading into each AI assistant required custom development, resulting in severe fragmentation. The ACP read-only service encapsulates index queries into interfaces that Agents can directly call, meaning AI assistants in editors no longer need to understand the codebase by repeatedly executing shell commands or full-disk greps—instead, they can precisely obtain structured results just like calling an API. This "tool-as-a-service" model is becoming the infrastructure standard for AI-native development tools.

The author gives a typical example: asking the Agent "find the implementation of SearchString and explain the call chain." The Agent doesn't need to scan the entire repository first; instead, it directly uses the index service to get results in 5 milliseconds—6 hits across 4 files—and then explains the call relationships based on these results.

The significance of this design is that it saves both developers and AI from repeatedly scanning the repository. As AI programming becomes increasingly widespread, it's the norm for Agents to frequently search codebases. If every search meant a full scan, it would be both slow and extremely resource-intensive. Treating the index as shared infrastructure precisely addresses this pain point.

It's worth noting that AI Agents are especially sensitive to context consumption—large models have limited context windows and are billed per token. If an Agent stuffs large amounts of irrelevant code into the context every time, it not only wastes computing power but also dilutes key information, leading to lower-quality answers. Precise index retrieval allows the Agent to obtain only the truly relevant code snippets, which directly helps improve both the accuracy and cost-effectiveness of AI programming.

Observations and Reflections: The Direction of Development Tools in the AI Era

Looking at the project as a whole, this is a classic case of "using AI to build AI tools"—the author used Cursor + Codex to develop the plugin, then in turn handed the plugin's search capabilities to AI Agents, forming a positive feedback loop between tools and agents.

This pattern hints at a trend: development tools in the AI era are shifting from "for human use" to "for shared human-machine use." Capabilities like indexing, search, and context, which originally served human developers, are being redesigned into service interfaces that Agents can efficiently invoke as well. Whoever gets this kind of infrastructure right will secure a key position in the AI programming workflow.

The author also stated plans to open-source the project and support mainstream editors like VS Code. For teams long plagued by large-repository search performance issues, tools like this are worth continued attention.

Key Takeaways