Local file link with backslash-escaped parentheses in filename fails to open (file lookup doesn't un-escape before resolving)
Summary
A markdown link to a local file whose filename contains parentheses fails to resolve when clicked, even when the parentheses are correctly backslash-escaped per CommonMark. The failure is confirmed to be caused by the click-to-open/file-resolution logic not un-escaping the backslash sequences before performing the file-system lookup.
Reproduction
- Create a local file whose name contains parentheses, e.g.
Notes (Draft).md. - Have Claude (or type manually) a markdown link to it using the CommonMark-correct backslash-escaped form:
[Notes (Draft).md](Notes \(Draft\).md). - Click the rendered link.
Expected: the file opens (or a preview/citation card shows its content), the same as it does for an identically-formatted link to a file with no special characters in its name.
Actual: "Couldn't read this file. It may have been deleted or moved, or it lives outside the working directory." The path shown in the error card still contains the literal escape backslashes (\(, \)).
Root cause (confirmed via a controlled test)
Right-clicking the broken link and choosing "Copy path" surfaces the exact path the client attempted to resolve. It is the fixed local root concatenated directly with the raw, still-escaped relative destination text from the markdown — the backslash escape characters are never stripped before the file-system lookup. Since the real on-disk file has plain parentheses (no backslashes), the lookup fails.
This was isolated with a matched pair of otherwise-identical test files:
- A short file with no special characters in its name: link resolves and opens correctly.
- An equally short file with parentheses in its name, linked via the correctly-escaped form: fails identically to a much longer/more complex filename tested earlier, ruling out path length as a factor.
The parser that renders the link itself appears to handle the escaping correctly (it doesn't truncate the link early at the first unescaped-looking )), but a separate, later step that resolves the destination to a real file does not undo the escaping first. These two logical layers disagree on what \(/\) means.
Impact
There is currently no markdown link format that reliably opens a local file whose name contains parentheses:
- Un-escaped parentheses: the link itself gets truncated at the first
)(standard CommonMark link-destination parsing behavior). - Backslash-escaped parentheses (the CommonMark-correct fix for the above): passes link parsing, but fails at the file-resolution step, per this report.
- Percent-encoding (
%28/%29): fails to open (percent-encoded characters are not decoded back before lookup). - Angle-bracket-wrapped destination (
<...>): the angle brackets themselves are treated as literal characters and the link fails to open.
The only current workaround is to avoid parentheses in filenames that will need to be linked at all.
Environment
- Claude Code / Claude Desktop app, Windows
- Local file link, relative path, file under the user's own working/home directory