[FEATURE/BUG] Improve project path encoding to preserve readability and improve third-party tool compatibility

Claude Code encodes project paths by replacing all non-ASCII characters with hyphens (-) when creating the ~/.claude/projects/ directory structure. This causes several issues:

1. Loss of readability: Project paths with Chinese characters become unrecognizable
2. Third-party integration problems: Tools like WayLog cannot match project paths because they expect different encoding schemes
3. Potential conflicts: Different Chinese paths could theoretically encode to the same directory name (low probability but possible)

Example

Original project path:

/Users/johnsmith/Documents/研究项目/2024/人工智能实验室_深度学习模型开发/MyProject

Current Claude Code encoding:

-Users-johnsmith-Documents---------2024-------------------------------MyProject

What WayLog (and other tools) expect:

-Users-johnsmith-Documents-研究项目-2024-人工智能实验室_深度学习模型开发-MyProject

Steps to Reproduce

1. Create a project in a directory with Chinese characters:

``bash
mkdir -p "/Users/john/中文项目/子目录"
cd "/Users/john/中文项目/子目录"
claude
``

1. Run a conversation in Claude Code

1. Check the created directory:

``bash
ls ~/.claude/projects/
``

1. Observe that Chinese characters are replaced with multiple hyphens

Current Encoding Implementation

Based on analysis, Claude Code appears to use:

def encode_path(path):
    result = path.replace('/', '-').replace('\\', '-')
    # Keep only ASCII alphanumeric characters
    result = ''.join([c if (c.isascii() and c.isalnum()) or c == '-' else '-' for c in result])
    return result

Suggested Solutions

Option 1: URL Encoding (Recommended)

Use percent-encoding (URL encoding) to preserve all characters while ensuring filesystem safety:

Pros:

• ✅ Preserves all information (reversible)
• ✅ Standard, well-known encoding scheme
• ✅ Easy to decode when needed
• ✅ Filesystem-safe

Option 2: Preserve Non-ASCII Characters

Only replace path separators and special filesystem characters, keeping Chinese characters:

Pros:

• ✅ More readable
• ✅ Compatible with modern filesystems (ext4, APFS, NTFS)
• ✅ Matches WayLog's expectations

Cons:

• ❌ May cause issues on some legacy filesystems

Option 3: Hybrid Approach

Use URL encoding for non-ASCII characters but preserve readability

Impact

This affects:

• Users: Cannot easily identify projects in ~/.claude/projects/
• Third-party tools: WayLog and other CLI tools cannot match Claude's project directories
• Ecosystem: Limits interoperability with other AI CLI tools

Additional Information

Claude Code Version: Latest (2.0.74+)
Platform: macOS (Darwin 24.6.0)
Filesystem: APFS (supports Unicode filenames)

Related Issues:

• #14838 - Chinese characters in file path autocomplete
• #1716 - UTF-8 Corruption Bug

Workaround Currently Used:

# Manual symlink to enable WayLog integration
cd ~/.claude/projects
ln -s "-Users-john-------project" "-Users-john-中文-project"