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 become glaringly obvious: every query scans the disk from scratch, forcing you to wait several seconds or even longer. For developers who need to frequently locate function implementations and trace call chains, this cumulative latency can severely slow down the development rhythm.

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

To solve this problem, the author leveraged the AI-assisted programming combination of Cursor + Codex to build a code search plugin from scratch. The core idea is: trading space for time—by pre-building a full-text index, 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 demonstration, in a massive 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 represents an order-of-magnitude improvement.

Underlying Technology: Lucene Indexing + BM25 Ranking

Indexing and Ranking Mechanism

This plugin is built on mature full-text retrieval technology. The author mentions using a Lucene-style 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, whereas an inverted index 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 up the table to obtain all matching documents, without ever touching the original files on disk. Lucene is an open-source full-text search library under the Apache Foundation and serves as the underlying kernel of well-known search engines like Elasticsearch and Solr. Polished over more than two decades, it has accumulated numerous mature solutions for tokenization, index compression, and incremental updates. The author's choice of a "Lucene-style" structure stands on the shoulders of this mature technology ecosystem, 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—much 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 benchmark for many search systems today. Its core idea is to assess relevance across three dimensions: term frequency (the more often a word appears in a document, the more relevant it is, though with a saturation ceiling), inverse document frequency (rarer words carry more discriminative power), and document length normalization (preventing long documents from gaining unfair advantage simply by containing more words). By contrast, simple keyword counting introduces clear bias in code retrieval—for example, a utility class of thousands of lines might get erroneously ranked at the top just because a keyword appears frequently. BM25 balances this well through length normalization, allowing function definitions and core implementations that truly match the query intent to rank at the top.

When the index is first built, the entire repository undergoes full-text analysis. While this process incurs some cost, common queries afterward typically return within 2 seconds, and hot queries can reach millisecond-level speeds.

Searching While Indexing

One noteworthy design is that you can start searching without waiting for the index to be fully built. The plugin supports querying while building the index on disk, and performs incremental updates when files change—rather than a full rebuild. This design greatly reduces the waiting cost of onboarding a large repository for the first time and makes index maintenance lightweight.

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

Rich Code Query Capabilities

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

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

In terms of interactive experience, the plugin adopts a streaming loading strategy: large result sets display the first batch of hits first, then progressively stream in subsequent results, avoiding making users stare at a blank screen for extended periods.

There are also several efficiency-boosting detail designs:

• Multiple tabs and locking: retaining multiple search contexts for easy comparison
• Alt + equals: directly search the currently selected code snippet
• Shift to quickly open files, switching between indexed header files and source files
• For scenarios like grep-style searches, it can directly open the corresponding type

Core Highlight: Read-Only Index Service for AI Agents

Index Sharing and Write Takeover

The plugin supports multiple instances sharing the same master index: one process handles writing while another accesses read-only; when the writer closes, the reader can automatically take over the write responsibility. This mechanism enables IDE plugins and other tools to work collaboratively, avoiding the resource waste of duplicate index building.

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 can occupy several GB of space and take minutes to build, letting multiple tools share the same index rather than each rebuilding its own saves not just disk space, but also precious build time and CPU resources.

ACP Read-Only Service and AI Collaboration

The most crucial 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 the source of calls.

ACP (Agent Client Protocol) is a recently emerging class of standardized protocols aimed at AI agents. Its philosophy is closely aligned with the MCP (Model Context Protocol) launched by Anthropic—both aim to enable large models to invoke external tools and data sources in a unified, structured manner. Before such protocols existed, every AI assistant had to develop custom integrations for capabilities like code search and file reading, resulting in severe fragmentation. The ACP read-only service encapsulates index queries into interfaces that agents can call directly, meaning AI assistants in editors no longer need to understand the codebase by repeatedly executing shell commands and full-disk greps—instead, they obtain structured results as precisely as 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 obtains results through the index service in 5 milliseconds, returning 6 hits across 4 files, and then explains the call relationships based on these results.

The significance of this design is that it frees both developers and AI from repeatedly scanning the repository. In today's era of rapidly proliferating AI programming, agents frequently retrieving codebases is the norm. If every retrieval required a full-disk scan, it would be not only slow but also extremely resource-intensive. Treating the index as shared infrastructure precisely addresses this pain point.

It's worth mentioning that AI agents are especially sensitive to context consumption—large models have limited context windows and are billed by token. If an agent stuffs large amounts of irrelevant code into its context every time, it not only wastes compute but also dilutes key information, degrading answer quality. Precise index retrieval allows the agent to obtain only genuinely relevant code snippets, directly benefiting both the accuracy and cost-effectiveness of AI programming.

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

Looking at the entire project, this is a textbook case of "using AI to build AI tools"—the author uses Cursor + Codex to develop the plugin, and in turn hands the plugin's search capabilities over to AI agents, forming a positive feedback loop between tools and intelligent agents.

This pattern hints at a trend: development tools in the AI era are shifting from "for humans" to "shared by humans and machines." Capabilities like indexing, searching, and context—originally designed to serve human developers—are being redesigned into service interfaces that agents can also efficiently invoke. Whoever gets this kind of infrastructure right will occupy a key position in the AI programming workflow.

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

Key Takeaways