[FEATURE] Symbol autocomplete when referencing files with @

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, Claude Code supports @ file references with autocomplete - when typing @src/auth, the CLI suggests matching files. This is great for including entire files as context.

However, there's no way to reference specific symbols (functions, classes, methods, variables) within a file. Users must either:

1. Include the entire file (wasteful for large files when only one function is relevant)
2. Manually type out symbol names (error-prone, no discoverability)
3. Copy-paste the relevant code snippet (breaks the conversational flow)

Example scenario:

User: "Can you explain what @src/services/auth.ts:validateToken does?"
                                              ^^^^^^^^^^^^^^^^
                                              No autocomplete here - user must
                                              remember exact function name

This creates friction when:

• Working with large files where only specific functions are relevant
• Exploring unfamiliar codebases (users don't know what symbols exist)
• Referencing deeply nested methods like ClassName.prototype.method

Proposed Solution

xtend the @ autocomplete to support symbol references using a delimiter (: or #):

@file.ts                    # Current behavior - reference whole file
@file.ts:functionName       # NEW - reference specific function
@file.ts:ClassName          # NEW - reference class/interface
@file.ts:ClassName.method   # NEW - reference class method

When the user types @path/to/file.ts:, Claude Code would show an autocomplete menu with the symbols in that file:

> Explain what @src/services/auth.ts:
                                     +--------------------------+
                                     | f  validateToken         |
                                     | f  refreshToken          |
                                     | f  hashPassword          |
                                     | C  AuthService           |
                                     | I  AuthConfig            |
                                     | v  DEFAULT_EXPIRY        |
                                     +--------------------------+
                                     f=function C=class I=interface v=variable

When processing the prompt, only the referenced symbol's code would be included as context (rather than the entire file).

Benefits

• Precision: Include only relevant code, saving context window
• Discoverability: Users can explore symbols without reading the file first
• Accuracy: No typos in symbol names
• Familiar UX: Similar to IDE "Go to Symbol" or GitHub's symbol search

Alternative Solutions

Alternative 1: Line range references

Support line ranges instead of symbols:

@file.ts#L42        # Single line
@file.ts#L42-L60    # Line range

Pros: Simple, language-agnostic
Cons: Requires users to know line numbers, breaks when code changes

Alternative 2: Fuzzy symbol search in prompt

Instead of autocomplete, let Claude search for symbols when processing the prompt:

User: "Explain the validateToken function in @src/auth.ts"
Claude: [internally searches for validateToken, includes relevant code]

Pros: No UI changes needed, works today with good prompting
Cons: Less precise, no discoverability, relies on Claude's interpretation

Alternative 3: IDE-only implementation

Implement symbol completion only in VS Code/JetBrains extensions, leveraging native IDE capabilities.

Pros: Leverages existing IDE infrastructure
Cons: Terminal CLI users don't benefit, inconsistent experience across surfaces

Current Workaround

Users can manually specify symbols with careful prompting:

Look at the validateToken function in @src/services/auth.ts and explain
what it does. Focus only on that function.

This works but lacks discoverability and is error-prone for exact symbol names.

Priority

High - Significant impact on productivity

Feature Category

Interactive mode (TUI)

Use Case Example

_No response_

Additional Context

• Similar features exist in GitHub (symbol search), VS Code (Ctrl+Shift+O), and other tools
• This would complement the existing @ file completion rather than replace it