[BUG] ClaudeCodeAdd fails when adding a file in a directory with a `$`

[geoff-tw]

Bug Description

When trying to add a file in a pathname that has a $ in it (for example, src/routes/$post/index.tsx) in the buffer to Claude Code, it will throw an error. You have to manually bring it in to context with @ and search for the file, where it can then be added without an issue.

To Reproduce

Steps to reproduce the behavior:

1. Start Claude Code integration.
2. Create a file that is inside a directory with a $ in it.
3. Add the file to the buffer.
4. You will see an error.

Expected Behavior

The file should be added to the buffer like any other.

Environment

• Neovim version: [e.g. 0.12.3]
• Claude Code CLI version: [e.g. 2.1.179]
• OS: [e.g. macOS 26.5.1]
• Plugin version: [e.g. 0.2.0]

Error Messages

[ClaudeCode] [command] [ERROR] ClaudeCodeAdd: File or directory does not exist: <file>

[geoff-tw]

Not sure if this is the actual cause, but based on Claude's exploration it's suggesting that the file path is being supplied to vim.fn.expand() which treats $ as an environment variable reference and replaces undefined ones with an empty string. This is consistent with the error I get for a file located in test/$id/hello.txt.

The same issue would also exist in the openFile MCP tool in lua/claudecode/tools/open_file.lua. The fix is to use the already existing require("claudecode.utils").expand_tilde() helper which would preserve the $ along with other special chars.

[ThomasK33]

Note

This triage report is AI-generated using Claude Code

Status: reproduced and confirmed

This behaviour has been reproduced and confirmed as a bug. The cause suggested in the issue thread — that the path is handed to vim.fn.expand(), which treats $post as an environment variable and substitutes the empty string for it — is correct.

Root cause

:ClaudeCodeAdd and the openFile MCP tool both pass the supplied path through vim.fn.expand(), which performs shell-style expansion, including environment-variable substitution. For a path whose directory is literally named $post, expand() reads $post as the (undefined) environment variable post and replaces it with an empty string:

src/routes/$post/index.tsx  ──vim.fn.expand()──▶  src/routes//index.tsx   (does not exist)

The subsequent filereadable() / isdirectory() check then fails, even though the file exists on disk. This was verified directly: for the same path, filereadable(<literal>) returns 1 and libuv fs_stat() succeeds, whereas filereadable(vim.fn.expand(<literal>)) returns 0. The command-line layer is not involved — a user-command argument keeps its literal $; only expand() mangles it.

Affected call sites

Two call sites are affected, both confirmed:

Location	Trigger	Observed error
lua/claudecode/init.lua:1033	:ClaudeCodeAdd <path>	ClaudeCodeAdd: File or directory does not exist: .../routes//index.tsx
lua/claudecode/tools/open_file.lua:110	openFile tool (invoked by Claude)	File not found: .../routes//index.tsx

The second site is worth highlighting: because openFile is driven by Claude itself, any attempt by Claude to open a real file under a $-named directory fails — not only manual :ClaudeCodeAdd invocations. This is consistent with the note in the issue that a file can still be brought in via @-search, which routes through a different, non-expand() path.

The other vim.fn.expand() usages in the codebase do not appear to be at risk for this issue:

• lua/claudecode/terminal.lua:241 uses the special %:p token (current-file absolute path), not env-substitution of a literal string;
• lua/claudecode/cwd.lua:14, lua/claudecode/terminal.lua:256 and :260, and lua/claudecode/lockfile.lua expand configuration-supplied directories (and ~/.claude/ide), where $VAR / ~ expansion is the intended behaviour.

Suggested fix

The fix proposed in the issue thread holds up. At the two affected sites, vim.fn.expand(x) can be replaced with the existing helper require("claudecode.utils").expand_tilde(x), which expands only a leading ~ / ~/ and leaves $, globs and everything else untouched. This was verified: expand_tilde(<$-path>) returns the path unchanged and filereadable() then returns 1, while expand_tilde("~/x") still resolves to <home>/x.

Regression coverage could be added to tests/unit/claudecode_add_command_spec.lua and tests/unit/tools/open_file_spec.lua, asserting that a path containing $ passes the readability check.

One behavioural trade-off is worth flagging for consideration: switching to expand_tilde means a typed argument such as $HOME/foo, or a glob like src/*.lua, would no longer be expanded by these two entry points. This seems acceptable — such inputs are rare for these paths, which usually arrive already-resolved from buffers/explorers, and preserving real $-named files is the more common and higher-impact case — but it is a deliberate change in behaviour.

Reproduction

Two artifacts were created. Both were screened and contain no secrets or personal information. Absolute paths in the output below are redacted to <repo>.

Headless, self-verifying script

This drives the real :ClaudeCodeAdd command and the real openFile handler against actual files on disk (no WebSocket server or Claude CLI required — the failure occurs at the expand() / filereadable() gate). It exits 1 when the bug is present and 0 once fixed, and includes a control (a sibling file without $) plus a preview of the proposed fix.

Output on current main:

-- mechanism --
  literal path        : <repo>/.../src/routes/$post/index.tsx
  exists on disk (uv) : true
  filereadable(literal): 1
  vim.fn.expand(...)   : <repo>/.../src/routes//index.tsx
  filereadable(expand) : 0   (<- expand() dropped the $post segment)

[A] :ClaudeCodeAdd  <$-path file that exists>
  error logged : ClaudeCodeAdd: File or directory does not exist: <repo>/.../src/routes//index.tsx
  reached send : false
  => BUG: existing file rejected

[B] :ClaudeCodeAdd  <control: same path, no $>
  reached send : true
  => ok: file accepted (harness sound)

[C] openFile MCP tool handler  <$-path file that exists>
  error thrown : File not found: <repo>/.../src/routes//index.tsx
  => BUG: existing file reported not found

-- proposed fix: require('claudecode.utils').expand_tilde --
  filereadable(expand_tilde)  : 1   (<- $ preserved, file found)
  tilde still expands         : yes

== verdict ==
BUG #285 REPRODUCED

Run with: nvim --headless -u NONE -l scripts/repro_issue_285.lua

scripts/repro_issue_285.lua

-- Reproduction / verification for issue #285:
--   "[BUG] ClaudeCodeAdd fails when adding a file in a directory with a `$`"
--   https://github.com/coder/claudecode.nvim/issues/285
--
-- Root cause (one defect, two call sites): user-supplied file paths are passed
-- through vim.fn.expand(), which performs SHELL-STYLE EXPANSION -- including
-- environment-variable substitution. A real path segment like `$post` (common in
-- TanStack Router / file-based routing, e.g. `src/routes/$post/index.tsx`) is
-- read by expand() as the env var `$post`; since it is undefined, expand()
-- replaces it with the empty string. `src/routes/$post/index.tsx` therefore
-- becomes `src/routes//index.tsx`, which does not exist, so the subsequent
-- filereadable()/isdirectory() check fails:
--
--   * lua/claudecode/init.lua:1033  (the :ClaudeCodeAdd command)
--       file_path = vim.fn.expand(file_path)
--       if filereadable(file_path)==0 and isdirectory(file_path)==0 -> ERROR
--   * lua/claudecode/tools/open_file.lua:110  (the openFile MCP tool)
--       local file_path = vim.fn.expand(params.filePath)
--       if filereadable(file_path)==0 -> ERROR "File not found"
--
-- The command-line layer is NOT to blame: a user-command arg keeps its literal
-- `$` (verified separately); only expand() mangles it.
--
-- The proposed fix (from the reporter) is to use the existing
-- require("claudecode.utils").expand_tilde() helper, which expands a leading
-- `~`/`~/` but leaves `$`, globs, and every other character untouched. Scenario D
-- demonstrates that this helper preserves the `$` path while still expanding `~`.
--
-- This script drives the REAL :ClaudeCodeAdd command (registered via
-- M._create_commands()) and the REAL open_file.handler against ACTUAL files on
-- disk. No WebSocket server or Claude CLI is needed: the bug fires at the
-- expand()+filereadable() gate, before any send/broadcast. M.state.server is
-- stubbed truthy only to pass the "integration not running" guard, and
-- M.send_at_mention is stubbed so the control case can confirm it reached the
-- send path (i.e. passed the gate).
--
-- Run from the repo root:
--   nvim --headless -u NONE -l scripts/repro_issue_285.lua
--
-- Exit code: 1 if the bug is present (a file that EXISTS is rejected), 0 if fixed.
-- The detailed verdict is printed to stdout either way.

local script_path = debug.getinfo(1, "S").source:sub(2)
local repo_root = vim.fn.fnamemodify(script_path, ":h:h")
vim.opt.rtp:prepend(repo_root)

local function out(msg)
  io.stdout:write(msg .. "\n")
end

local uv = vim.loop

-- ----------------------------------------------------------------------------
-- Arrange: real files on disk, one with a `$` segment, one without (control).
-- ----------------------------------------------------------------------------
local work = vim.fn.tempname() .. "_issue285"
local dollar_dir = work .. "/src/routes/$post"
local plain_dir = work .. "/src/routes/post"
local file_dollar = dollar_dir .. "/index.tsx"
local file_plain = plain_dir .. "/index.tsx"

vim.fn.mkdir(dollar_dir, "p")
vim.fn.mkdir(plain_dir, "p")
for _, f in ipairs({ file_dollar, file_plain }) do
  local fh = assert(io.open(f, "w"))
  fh:write("export default function Page() { return null }\n")
  fh:close()
end

-- Ground truth via libuv (raw syscall, performs NO `$`/`~` expansion): both
-- files genuinely exist on disk at their literal paths.
local function exists_on_disk(p)
  return uv.fs_stat(p) ~= nil
end
assert(exists_on_disk(file_dollar), "setup: $-path file was not created on disk")
assert(exists_on_disk(file_plain), "setup: control file was not created on disk")

-- ----------------------------------------------------------------------------
-- Capture logger output. `logger` is a module-level singleton table required by
-- init.lua, so replacing its functions here is seen by the command's closure.
-- ----------------------------------------------------------------------------
local logger = require("claudecode.logger")
local log = {} -- { {level=, component=, msg=}, ... }
local function capture(level)
  return function(component, ...)
    local parts = {}
    for _, v in ipairs({ ... }) do
      parts[#parts + 1] = tostring(v)
    end
    log[#log + 1] = { level = level, component = component, msg = table.concat(parts, " ") }
  end
end
logger.error = capture("error")
logger.warn = capture("warn")
logger.debug = capture("debug")
logger.info = capture("info")

local function last_error()
  for i = #log, 1, -1 do
    if log[i].level == "error" then
      return log[i].msg
    end
  end
  return nil
end
local function clear_log()
  log = {}
end

-- ----------------------------------------------------------------------------
-- Register the REAL commands and stub just enough to pass the run-state guard
-- and observe whether the send path was reached.
-- ----------------------------------------------------------------------------
local cc = require("claudecode")
cc.state = cc.state or {}
cc.state.server = { _stub = true } -- truthy: pass the "integration is not running" guard
cc.state.config = cc.state.config or {}

local sent = {}
cc.send_at_mention = function(file_path, start_line, end_line, context)
  sent[#sent + 1] = { file_path = file_path, start_line = start_line, end_line = end_line, context = context }
  return true, nil
end

cc._create_commands()

-- ----------------------------------------------------------------------------
-- Helpers to run the real command / real tool handler.
-- ----------------------------------------------------------------------------
local function run_add(path)
  clear_log()
  -- Invoke exactly as a mapping / file-explorer integration would: literal arg.
  vim.cmd({ cmd = "ClaudeCodeAdd", args = { path } })
end

local open_file = require("claudecode.tools.open_file")
local function run_open(path)
  local ok, err = pcall(open_file.handler, { filePath = path, makeFrontmost = false })
  return ok, err
end

-- ----------------------------------------------------------------------------
out("== issue #285 reproduction ($ in path mangled by vim.fn.expand) ==")
out(("Neovim: %s"):format(tostring(vim.version())))
out(("work dir: %s"):format(work))
out("")

-- Diagnostic: show exactly how expand() mangles the path vs the literal truth.
local expanded = vim.fn.expand(file_dollar)
out("-- mechanism --")
out(("  literal path        : %s"):format(file_dollar))
out(("  exists on disk (uv) : %s"):format(tostring(exists_on_disk(file_dollar))))
out(("  filereadable(literal): %d  (file functions do NOT expand $)"):format(vim.fn.filereadable(file_dollar)))
out(("  vim.fn.expand(...)   : %s"):format(expanded))
out(("  filereadable(expand) : %d  (<- expand() dropped the $post segment)"):format(vim.fn.filereadable(expanded)))
out("")

-- Scenario A: the issue. :ClaudeCodeAdd on a file that EXISTS but has a `$`.
run_add(file_dollar)
local a_err = last_error()
local a_reached_send = #sent > 0
out("[A] :ClaudeCodeAdd  <$-path file that exists>")
out(("  error logged : %s"):format(a_err or "(none)"))
out(("  reached send : %s"):format(tostring(a_reached_send)))
local a_bug = (a_err ~= nil) and not a_reached_send
out(("  => %s"):format(a_bug and "BUG: existing file rejected" or "ok: file accepted"))
out("")

-- Scenario B: control. Same command, sibling file WITHOUT `$`. Must always pass
-- the gate and reach the send path -- proves the harness is sound and the only
-- variable is the `$`.
sent = {}
run_add(file_plain)
local b_err = last_error()
local b_reached_send = #sent > 0
out("[B] :ClaudeCodeAdd  <control: same path, no $>")
out(("  error logged : %s"):format(b_err or "(none)"))
out(("  reached send : %s"):format(tostring(b_reached_send)))
out(("  => %s"):format(b_reached_send and "ok: file accepted (harness sound)" or "UNEXPECTED: control failed"))
out("")

-- Scenario C: the second call site -- the openFile MCP tool handler.
local c_ok, c_err = run_open(file_dollar)
local c_msg = type(c_err) == "table" and tostring(c_err.data or c_err.message) or tostring(c_err)
out("[C] openFile MCP tool handler  <$-path file that exists>")
if c_ok then
  out("  result       : opened (no error)")
else
  out(("  error thrown : %s"):format(c_msg))
end
local c_bug = (not c_ok) and c_msg:find("not found", 1, true) ~= nil
out(("  => %s"):format(c_bug and "BUG: existing file reported not found" or "ok: file accepted"))
out("")

-- Scenario D: the proposed fix. expand_tilde() preserves `$` (and globs) while
-- still expanding a leading `~`.
local utils = require("claudecode.utils")
local et_dollar = utils.expand_tilde(file_dollar)
local home = os.getenv("HOME") or ""
local et_tilde = utils.expand_tilde("~/some/$dir/file.tsx")
out("-- proposed fix: require('claudecode.utils').expand_tilde --")
out(("  expand_tilde($-path)        : %s"):format(et_dollar))
out(("  filereadable(expand_tilde)  : %d  (<- $ preserved, file found)"):format(vim.fn.filereadable(et_dollar)))
out(("  expand_tilde('~/x/$dir/..') : %s"):format(et_tilde))
local tilde_ok = home ~= "" and et_tilde == (home .. "/some/$dir/file.tsx")
out(("  tilde still expands         : %s"):format(tilde_ok and "yes" or "(HOME unset; skipped)"))
out("")

-- ----------------------------------------------------------------------------
-- Verdict
-- ----------------------------------------------------------------------------
pcall(vim.fn.delete, work, "rf")

out("== verdict ==")
local reproduced = a_bug or c_bug
if not b_reached_send then
  out("WARNING: control scenario B failed; harness may be unsound -- treat results with care.")
end
if reproduced then
  out("BUG #285 REPRODUCED:")
  if a_bug then
    out("  - :ClaudeCodeAdd rejected an existing file because expand() dropped the $ segment.")
  end
  if c_bug then
    out("  - openFile MCP tool reported an existing file as 'not found' for the same reason.")
  end
  out("  Fix: replace vim.fn.expand() with claudecode.utils.expand_tilde() at both call sites.")
else
  out("FIXED: the $-path file is accepted by both :ClaudeCodeAdd and openFile.")
end

io.stdout:flush()
vim.cmd("cquit " .. (reproduced and 1 or 0))

Interactive fixture

A fixture under fixtures/issue-285/ ships a real file at sample/src/routes/$post/index.tsx. Loading it with source fixtures/nvim-aliases.sh && vv issue-285 opens that file; running :Repro285 (or <leader>x) drives the real command and tool and prints a one-line PASS/FAIL verdict. This was verified live in a Neovim TUI, where the verdict read issue #285 REPRODUCED, with :ClaudeCodeAdd and the openFile tool both failing on .../src/routes//index.tsx (note the // — the $post segment has vanished).

fixtures/issue-285/init.lua

-- Fixture for issue #285:
--   "[BUG] ClaudeCodeAdd fails when adding a file in a directory with a `$`"
--   https://github.com/coder/claudecode.nvim/issues/285
--
-- The sample tree under fixtures/issue-285/sample/ contains a REAL file whose
-- parent directory is literally named "$post":
--   fixtures/issue-285/sample/src/routes/$post/index.tsx
--
-- :ClaudeCodeAdd and the openFile MCP tool both pass the path through
-- vim.fn.expand(), which substitutes "$post" with the (undefined) env var ->
-- the path becomes ".../src/routes//index.tsx", which does not exist, so the
-- command reports "File or directory does not exist".
--
-- Usage (from repo root):
--   source fixtures/nvim-aliases.sh && vv issue-285
-- The $-path file opens automatically. Then either:
--   * press <leader>x   -> runs :Repro285 (self-contained verdict), or
--   * run :Repro285     -> drives the REAL :ClaudeCodeAdd + openFile on the
--                          $-path file and echoes a one-line PASS/FAIL verdict.
-- For a fully hand-driven check: :ClaudeCodeStart, then
--   :ClaudeCodeAdd <paste the absolute path printed in the banner>   (FAILS), vs
--   :ClaudeCodeAdd %                                                 (works),
-- then read :messages.

local config_dir = vim.fn.stdpath("config")
local repo_root = vim.fn.fnamemodify(config_dir, ":h:h")
vim.opt.rtp:prepend(repo_root)

vim.g.mapleader = " "
vim.g.maplocalleader = "\\"
vim.o.laststatus = 2

local ok, claudecode = pcall(require, "claudecode")
assert(ok, "Failed to load claudecode.nvim from repo root: " .. tostring(claudecode))

claudecode.setup({
  auto_start = false,
  log_level = "info",
  terminal = { provider = "native", auto_close = false },
})

-- Resolve the real $-path sample file shipped with this fixture.
local sample = repo_root .. "/fixtures/issue-285/sample/src/routes/$post/index.tsx"

-- Open it so the buffer name itself carries the `$` (this is the file a user
-- would be "adding to the buffer"). fnameescape keeps `$` literal for :edit.
vim.cmd("edit " .. vim.fn.fnameescape(sample))

local banner_buf = vim.api.nvim_create_buf(false, true)
vim.api.nvim_buf_set_lines(banner_buf, 0, -1, false, {
  "claudecode.nvim -- issue #285 reproduction fixture",
  "",
  "Sample file (exists on disk, parent dir is literally '$post'):",
  "  " .. sample,
  "",
  "Press <leader>x  (or run :Repro285) for a one-line PASS/FAIL verdict.",
  "",
  "Manual check:",
  "  :ClaudeCodeStart",
  "  :ClaudeCodeAdd " .. sample .. "      <- FAILS (expand drops $post)",
  "  :ClaudeCodeAdd %                                  <- works (% = literal buffer name)",
  "  :messages",
  "",
  "Expected on UNFIXED code:",
  "  [ClaudeCode] [command] [ERROR] ClaudeCodeAdd: File or directory does",
  "  not exist: .../src/routes//index.tsx   (note the '//' -- $post vanished)",
})
vim.bo[banner_buf].modifiable = false
vim.bo[banner_buf].buftype = "nofile"

-- Capture the plugin logger so the verdict can show the exact error it logs.
local logger = require("claudecode.logger")
local function with_captured_logger(fn)
  local saved = { error = logger.error, debug = logger.debug, warn = logger.warn, info = logger.info }
  local lines = {}
  local function cap(level)
    return function(component, ...)
      local parts = {}
      for _, v in ipairs({ ... }) do
        parts[#parts + 1] = tostring(v)
      end
      lines[#lines + 1] = { level = level, msg = table.concat(parts, " ") }
    end
  end
  logger.error, logger.debug, logger.warn, logger.info = cap("error"), cap("debug"), cap("warn"), cap("info")
  local ok_run, err = pcall(fn)
  logger.error, logger.debug, logger.warn, logger.info = saved.error, saved.debug, saved.warn, saved.info
  return lines, ok_run, err
end

local function last_error(lines)
  for i = #lines, 1, -1 do
    if lines[i].level == "error" then
      return lines[i].msg
    end
  end
  return nil
end

---Drive the REAL :ClaudeCodeAdd and openFile on the $-path sample, then echo a
---one-line verdict. Self-contained: if the integration isn't started, the
---run-state guard is stubbed so the expand()/filereadable() gate is still
---reached (that gate is where #285 lives -- no Claude connection is involved).
local function repro_285()
  local cc = require("claudecode")
  cc.state = cc.state or {}
  local restore_server = false
  if not cc.state.server then
    cc.state.server = { _stub = true }
    restore_server = true
  end
  local saved_send = cc.send_at_mention
  local reached_send = false
  cc.send_at_mention = function()
    reached_send = true
    return true, nil
  end

  local lines = with_captured_logger(function()
    vim.cmd({ cmd = "ClaudeCodeAdd", args = { sample } })
  end)
  local add_err = last_error(lines)

  local open_ok, open_err = pcall(require("claudecode.tools.open_file").handler, {
    filePath = sample,
    makeFrontmost = false,
  })
  local open_msg = type(open_err) == "table" and tostring(open_err.data or open_err.message) or tostring(open_err)

  cc.send_at_mention = saved_send
  if restore_server then
    cc.state.server = nil
  end

  local add_bug = (add_err ~= nil) and not reached_send
  local open_bug = (not open_ok) and open_msg:find("not found", 1, true) ~= nil
  local reproduced = add_bug or open_bug

  local report = {}
  report[#report + 1] = {
    reproduced and "issue #285 REPRODUCED" or "issue #285 FIXED",
    reproduced and "ErrorMsg" or "MoreMsg",
  }
  vim.api.nvim_echo(report, true, {})
  -- Detail lines land in :messages.
  vim.api.nvim_echo({
    { ("  ClaudeCodeAdd : %s"):format(add_err or (reached_send and "accepted (reached send)" or "no error")) },
  }, true, {})
  vim.api.nvim_echo({
    { ("  openFile tool : %s"):format(open_ok and "opened" or open_msg) },
  }, true, {})
end

vim.api.nvim_create_user_command("Repro285", repro_285, { desc = "Repro #285 ($ in path)" })
vim.keymap.set("n", "<leader>x", repro_285, { desc = "Repro #285 ($ in path)" })

fixtures/issue-285/sample/src/routes/$post/index.tsx

// Sample file for issue #285. The PARENT directory is literally named "$post"
// (a TanStack Router / file-based-routing dynamic segment). The `$` is what
// trips vim.fn.expand(): it reads `$post` as the (undefined) env var `post` and
// substitutes the empty string, so the path the plugin checks no longer exists.
export default function Post() {
  return null
}