Architecture: How should the @file mention system be designed for extensib...

Documentation for Sessions

🏗️ Architecture: How should the @file mention system be designed for extensib...

Date: 2026-03-31
Time: 18:42:12 UTC
Session: gspace1-290.25
Agent: architecture
Confidence: 94%
Status: ✅ Documented

📋 Decision Context

Question:

How should the @file mention system be designed for extensibility while shipping with just file search?

Task: @mention system design

🎯 Decision Made

Chosen:

Provider-based MentionSource interface where each source (file, selection, terminal, errors) implements search(query) → MentionItem[]. File provider ships now using workspace.findFiles via extension host request/response. Mentions render as chips above the textarea, not inline in a contenteditable div.

Options Considered:

  1. Full multi-provider system from day 1 (@file, @selection, @terminal, @errors) — over-scoped
  2. Simple file search without provider abstraction — fast but paints into a corner
  3. Provider interface with file search only, designed for extension (chosen)
  4. contenteditable div with inline mention tokens — complex, fragile

💭 Reasoning

Every competitor uses @ mentions: Cursor (@file, @Codebase, @Web), Copilot (#file, #codebase), Cody (@file, @repo), Continue (@files, @docs). The provider interface ensures adding @selection/@terminal/@errors is just registering a new MentionSource — no structural changes needed. Using textarea + chip row (instead of contenteditable) avoids the notorious contenteditable complexity (cursor positioning, selection ranges, paste handling, IME issues). The chip row pattern matches the existing composer-att-row for file attachments. File search uses workspace.findFiles with a 200ms debounce and 50-result limit to avoid blocking in large monorepos. The request/response pattern uses the existing correlation ID system in api.ts.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation