[FEATURE] VS Code extension: filesystem path completion in @-mention (`../`, `~/`, absolute paths) like the CLI

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

I use both the Claude Code CLI in a terminal and the VS Code extension, and the @ file
reference works fundamentally differently in each — which makes the extension unusable for a
large part of my workflow.

In the CLI, @ is a filesystem path completer. I can type @../, @~/, @/etc/… and
walk the filesystem interactively, tabbing through directories. Referencing a file that lives
outside the current project is a two-second operation.

In the VS Code extension, @ is a fuzzy search over the workspace file index. There is no
notion of a path prefix: typing ../ matches nothing, and anything outside the workspace
folders simply does not exist as far as the picker is concerned. So for any file outside the
workspace root I have to abandon @ entirely and hand-type a full absolute path into the prompt
from memory — no completion, no validation, and typos only surface when a tool call fails.

This matters a lot for how I actually use Claude Code: my workspace is usually opened at one
project, but plenty of tasks need a file from a sibling project, from ~/.config, from
~/Downloads, or from a scratch directory. The CLI handles this trivially; the extension makes
it a manual, error-prone step.

Proposed Solution

Make the extension's @ picker recognise path-shaped input and fall back to filesystem
completion, keeping the current fuzzy workspace search as the default behaviour.

Concretely, when the text after @ starts with a path prefix — /, ~/, ./, or ../ —
switch the suggestion source from the workspace index to directory listings on disk:

• @../ → lists entries of the parent directory of the workspace root
• @../other-project/sr → completes to ../other-project/src/
• @~/ → lists entries of the home directory
• @/home/user/… → completes absolute paths
• @confi (no path prefix) → unchanged, current fuzzy workspace search

Details that would make it feel like the CLI:

• Directories complete to a trailing / and let you keep typing to descend, rather than

terminating the completion.

• Directory entries are listed alongside files so navigation is possible, not just leaf matches.
• The inserted reference stays workspace-relative when the target is inside a workspace folder,

and absolute otherwise.

• Selecting a file outside the current working directories ideally registers it the way

/add-dir would, or at minimum warns instead of failing later at the permission layer.

A settings toggle (e.g. claude-code.atMention.filesystemCompletion) would be fine if the team
prefers this to be opt-in, though CLI parity as the default seems more consistent.

Alternative Solutions

Workarounds I currently use, and why each falls short:

1. Add the folder to the VS Code workspace (File > Add Folder to Workspace, multi-root).

Works, but it is a heavyweight, persistent change to my editor layout just to reference one
file once, and it pollutes search/explorer for the rest of the session.

1. /add-dir <path> — grants access, but does not give me completion in the @ picker, so

I still have to type the path by hand. (Related: #36123, closed as not planned.)

1. Type the absolute path in plain prose — works, but with zero completion or validation.
2. Drag and drop from the Explorer — only reaches files already visible in the workspace, so

it does not solve the out-of-workspace case. (Related: #73853.)

1. Run the CLI in the VS Code integrated terminal instead of the panel — this is what I

actually end up doing, because it restores full @ path completion while keeping IDE
integration. But it means giving up the extension panel altogether, which is a strange
outcome for two officially supported surfaces of the same product.

Priority

High - Significant impact on productivity

Feature Category

File operations

Use Case Example

1. My VS Code workspace is opened at ~/Documents/project-a.
2. I need Claude to compare a config file with the equivalent one in a sibling project:

~/Documents/project-b/config/app.yml.

1. In the CLI I type @../project-b/co + Tab and I am done in about two seconds.
2. In the extension, @../ matches nothing. I either add project-b as a second workspace root

(and remember to remove it later), or I hand-type the full absolute path and hope I got it
right.

1. With filesystem completion in the picker, the extension behaves like the CLI and the detour

disappears.

Same pattern, several times a day, for ~/.config/..., ~/Downloads/..., and scratch
directories outside any project.

Additional Context

Environment

• Claude Code CLI: 2.1.220
• VS Code extension: 2.1.221 (2.1.220 also installed), anthropic.claude-code-*-linux-x64
• VS Code: 1.131.0
• OS: Fedora Linux 44 (KDE Plasma), kernel 7.1.5
• Workspace: single-root

Related issues (none of which cover this request)

• #83768 — *[BUG] VS Code extension: @-mention file indexing only sees root-level files, not

subdirectories (ECONNREFUSED on local indexing service)*. Open. Adjacent symptom, but that is
a broken-index bug about files inside the workspace; this request is about deliberate
filesystem path navigation outside it. The two are independent — fixing the index would
still leave @../ meaningless.

• #36123 — Support /add-dir in IDE extensions (VS Code / JetBrains). Closed as not planned /

stale. About granting access to a directory, not about completing paths in the picker.

• #73853 — *[VSCode] Drag-and-drop file reference inserts absolute path instead of

workspace-relative path*. Touches the same "how is a reference inserted" surface and is worth
keeping consistent with the last bullet of the proposal.

Technical note

The CLI already implements exactly this completion logic, so the behaviour is specified by an
existing implementation rather than needing a new design — the gap is that the extension's
picker is wired to the workspace file index only.