Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [FEATURE] Tools should accept ~/ and relative paths, resolve via $HOME/$PWD instead of requiring absolute paths [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#45450•Fetched 2026-04-09 08:05:08
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
3
Author
tilotilo
Participants
tilotilo
Timeline (top)
labeled ×2cross-referenced ×1renamed ×1

Root Cause

Claude Code's file tools (Read, Edit, Write, Glob) require absolute paths in their parameters. This forces the LLM to hard-code the user's home directory path (e.g. /Users/mike.schmitt/...), which is a frequent source of silent failures because LLMs hallucinate usernames.

Fix Action

Fix / Workaround

Current workarounds:

  • CLAUDE.md instructions telling the model to use ~/ (is ignored by tools that reject it)
  • Expanding $HOME via a Bash call first, then passing the result to file tools (extra round-trip, still requires the LLM to copy the path correctly)
  • Users with simple usernames don't notice, but anyone with a non-ASCII or multi-syllable name hits this regularly
RAW_BUFFERClick to expand / collapse

Preflight Checklist

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

Problem Statement

Claude Code's file tools (Read, Edit, Write, Glob) require absolute paths in their parameters. This forces the LLM to hard-code the user's home directory path (e.g. /Users/mike.schmitt/...), which is a frequent source of silent failures because LLMs hallucinate usernames.

A user named "mike.schmitt" will routinely see Claude generate:

  • /Users/mike.schmidt/Work/project/file.rb (schmidt — is a more common spelling, hallucinated)
  • /home/mike.schmitt/Work/project/file.rb (wrong OS prefix)

LLMs default to the more common spelling of ambiguous names. This fails silently or produces "file not found" errors, wasting tokens and user time. Users can add CLAUDE.md instructions like "never hard-code my home directory" but the tool contract requires absolute paths, so the instruction fights the tool API.

Claude Code needs to be aware if a file location is under $PWD or not.

  • For files under $PWD, the LLM should use relative paths (./src/file.rb).
  • For files under $HOME but outside $PWD (e.g. ~/.claude/CLAUDE.md), the LLM should use $HOME directly! In neither case should the LLM attempt to spell out the username.

Proposed Solution

  1. Under $PWD: tools should accept and prefer relative paths (e.g. ./src/file.rb), resolved server-side against the working directory
  2. Under $HOME but outside $PWD: accept ~/, resolved server-side via $HOME
  3. Reject path traversal (../) that escapes $PWD — this addresses the security concern raised in issue #38270
  4. The LLM should never attempt to spell out the user's home directory path. Tools should resolve $HOME internally, not require the LLM to guess it.

Alternative Solutions

Current workarounds:

  • CLAUDE.md instructions telling the model to use ~/ (is ignored by tools that reject it)
  • Expanding $HOME via a Bash call first, then passing the result to file tools (extra round-trip, still requires the LLM to copy the path correctly)
  • Users with simple usernames don't notice, but anyone with a non-ASCII or multi-syllable name hits this regularly

Priority

High - Significant impact on productivity

Feature Category

File operations

Use Case Example

  1. User "mike.schmitt" asks Claude to edit ~/.claude/CLAUDE.md
  2. Claude must expand ~/ to /Users/mike.schmitt/ for the Edit tool
  3. Claude hallucinates /Users/mike.schmidt/ (more common spelling)
  4. Edit tool returns "file not found"
  5. Claude retries with another variation, wasting another round-trip
  6. User has to manually correct the path

With ~/ support: Claude passes ~/.claude/CLAUDE.md directly, tool resolves it server-side via $HOME, no hallucination possible.

For files under $PWD: Claude passes ./foo/bar/baz.rb, tool resolves against the working directory. No home directory path involved at all.

Additional Context

Security note: requiring absolute paths is actually less safe than relative paths scoped to $PWD.

  • Absolute paths can reference any location on the filesystem, easily escaping the project sandbox.
  • Relative paths scoped to $PWD and ~/ scoped to $HOME are naturally bounded.

Related: issue #38270 raises the complementary concern — relative paths are silently accepted when they should be validated.

Both issues stem from the same root cause: path handling is underdesigned.

The fix for both: tools should resolve paths against $PWD and $HOME server-side, and reject anything that escapes those boundaries.

This replaces the current model where the LLM constructs absolute paths (hallucination-prone) and tools silently accept whatever they get (no boundary enforcement).

extent analysis

TL;DR

The most likely fix is to modify the file tools to accept and resolve relative paths and ~/ notation server-side, using $PWD and $HOME as boundaries.

Guidance

  • Modify the file tools to accept relative paths (e.g., ./src/file.rb) and resolve them against the working directory ($PWD) server-side.
  • Update the tools to accept ~/ notation and resolve it server-side via $HOME, without requiring the LLM to spell out the user's home directory path.
  • Implement path validation to reject any paths that attempt to escape the boundaries of $PWD and $HOME, addressing the security concern.
  • Ensure the LLM never attempts to hallucinate the user's home directory path, instead relying on the tools to resolve paths internally.

Example

import os

def resolve_path(path):
    if path.startswith('./'):
        # Resolve relative path against $PWD
        return os.path.join(os.getcwd(), path)
    elif path.startswith('~'):
        # Resolve ~/ notation via $HOME
        return os.path.join(os.environ['HOME'], path[2:])
    else:
        # Reject absolute paths or invalid notation
        raise ValueError("Invalid path notation")

Notes

This solution assumes that the file tools have access to the $PWD and $HOME environment variables. Additionally, the implementation should ensure that the path resolution is done securely, without introducing any vulnerabilities.

Recommendation

Apply the workaround by modifying the file tools to accept and resolve relative paths and ~/ notation server-side, using $PWD and $HOME as boundaries. This approach addresses the root cause of the issue and provides a more secure and reliable solution.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#database connection#vector store#embedding generation#file not found

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING