Autocompletion Engine

Relevant source files

The following files were used as context for generating this wiki page:

• vibe/core/autocompletion/fuzzy.py
• vibe/core/autocompletion/file_indexer/indexer.py
• vibe/cli/autocompletion/path_completion.py
• vscode-extension/src/fileIndexer/PathCompleter.ts
• vscode-extension/src/fileIndexer/FileIndexer.ts
• vscode-extension/media/webview/chat.js
• tests/autocompletion/test_ui_chat_autocompletion.py

The Autocompletion Engine in QQcode provides real-time suggestions for slash commands (/) and file path mentions (@) within the interactive chat interface. It is designed to enhance developer productivity by allowing quick referencing of the codebase and execution of meta-actions without leaving the chat loop.

The system operates across both the TUI (Textual UI) and the VS Code extension, utilizing a combination of file indexing, fuzzy matching algorithms, and asynchronous event handling to provide responsive suggestions as the user types.

Sources: README.md:58-60, tests/autocompletion/test_ui_chat_autocompletion.py:27-35, vscode-extension/media/webview/chat.js:873-885

Core Components and Architecture

The autocompletion architecture is divided into the indexing layer, the matching logic, and the UI presentation layer.

File Indexing

The engine maintains a searchable index of the workspace to provide fast path completions. In the VS Code extension, this is managed by the FileIndexer, which crawls the workspace to create IndexEntry objects.

The diagram shows the logic flow when a user triggers a path completion request via the @ symbol.
Sources: vscode-extension/src/fileIndexer/PathCompleter.ts:114-142, vscode-extension/src/fileIndexer/PathCompleter.ts:187-227

Fuzzy Matching Logic

QQcode uses subsequence matching and word boundary detection to rank results. The matching logic ensures that even partial or non-contiguous strings can return relevant file paths.

Feature	Description
Subsequence Matching	Matches characters in the order they appear, even if separated by other characters.
Word Boundaries	Prioritizes matches that occur at the start of filenames or directory segments.
Recursive Search	Finds files deep in the directory tree even with partial path fragments.
Score Sorting	Suggestions are sorted by a match score (descending) then alphabetically.

Sources: tests/autocompletion/test_ui_chat_autocompletion.py:206-235, vscode-extension/src/fileIndexer/PathCompleter.ts:258-271

VS Code Implementation

In the VS Code extension, autocompletion is implemented as a bridge between the Webview UI and the TypeScript backend.

Path Completion Flow

When the user types an @ symbol in the chat webview, a requestFileCompletions message is dispatched to the extension host. The PathCompleter then processes the request using the current workspace root.

This sequence illustrates the asynchronous communication between the UI and the backend indexer.
Sources: vscode-extension/media/webview/chat.js:936-953, vscode-extension/src/chatView/ChatViewProvider.ts:204-232

Search Contexts

The PathCompleter builds a specific SearchContext based on the user's input to optimize performance:

• Top-level: Triggered by @, shows top-level files and directories.
• Immediate Children: Triggered by @path/, restricts search to the specified directory.
• Fuzzy: Triggered by @partial, searches the entire index for matches.

Sources: vscode-extension/src/fileIndexer/PathCompleter.ts:31-36, vscode-extension/src/fileIndexer/PathCompleter.ts:114-142

TUI Implementation (Textual)

The TUI implementation uses a CompletionPopup widget and a ChatInputContainer to manage user interactions.

UI Interaction Rules

• Activation: The popup appears when a slash (/) or at (@) symbol is detected at the start of a word.
• Navigation: Users use Up/Down arrows to navigate suggestions and Tab or Enter to apply them.
• Cycling: Pressing Shift+Tab in the TUI toggles between execution modes (Plan, Interactive, Auto-Approve) rather than navigating the popup.

Keyboard Shortcut	Action
Tab	Completes the selected command or path.
Enter	Submits the completed command and hides the popup.
Backspace	Hiding the popup if the trigger character is removed.
Escape	Dismisses the completion popup manually.

Sources: tests/autocompletion/test_ui_chat_autocompletion.py:48-59, tests/autocompletion/test_ui_chat_autocompletion.py:100-112, vscode-extension/media/webview/chat.js:101-125

Technical Specifications

Data Structures

The engine utilizes the following primary interfaces for data exchange:

// vscode-extension/src/fileIndexer/PathCompleter.ts
export interface CompletionSuggestion {
    label: string;      // The display text (e.g., "@src/index.ts")
    path: string;       // The relative path
    isDirectory: boolean;
}

// vscode-extension/src/fileIndexer/FileIndexer.ts
export interface IndexEntry {
    name: string;       // Filename
    rel: string;        // Relative path from root
    relLower: string;   // Lowercase path for fast matching
    isDir: boolean;
}

Sources: vscode-extension/src/fileIndexer/PathCompleter.ts:18-24, vscode-extension/src/fileIndexer/FileIndexer.ts (referenced by import)

Performance Constraints

To maintain UI responsiveness, the engine implements several limits:

• Indexing Limit: Processes up to 32,000 entries by default.
• Match Target: Stops searching after finding 100 potential matches.
• Display Limit: Returns a maximum of 50 suggestions to the UI.
• Debounce: Input events are debounced by 50ms before requesting completions.

Sources: vscode-extension/src/fileIndexer/PathCompleter.ts:11-13, vscode-extension/media/webview/chat.js:943-952

Conclusion

The Autocompletion Engine is a critical component of the QQcode user experience, providing a seamless bridge between natural language chat and the underlying filesystem. By combining efficient indexing with robust fuzzy matching, it ensures that developers can reference project resources with minimal friction across both CLI and IDE environments.