Feature Request: Implement Proper XDG Base Directory Specification Compliance

Summary

Claude Code currently stores all its files (configuration, data, and cache) in a single directory, which doesn't follow the XDG Base Directory specification. This feature request proposes reorganizing file storage to properly comply with XDG standards.

Current State

All Claude Code files are currently stored in either:

• ~/.claude/ (for user settings and CLAUDE.md)
• ~/.config/claude/ (for internal state, which is actually being used as a data directory)

Current ~/.config/claude/ contents:

~/.config/claude/
├── settings.json                    # ✓ Config (correct location)
├── claude_code_mcp_settings.json    # ✓ Config (correct location)
├── projects/                        # ✗ Data (should be in XDG_DATA_HOME)
├── todos/                           # ✗ Data (should be in XDG_DATA_HOME)
└── statsig/                         # ✗ Cache (should be in XDG_CACHE_HOME)

Proposed Structure

Following XDG Base Directory specification:

Configuration ($XDG_CONFIG_HOME/claude/ or ~/.config/claude/)

• settings.json - User settings
• settings.local.json - Local user settings
• claude_code_mcp_settings.json - MCP configuration
• CLAUDE.md - Global user preferences (alternative to ~/.claude/CLAUDE.md)

Data ($XDG_DATA_HOME/claude/ or ~/.local/share/claude/)

• projects/ - Conversation history
• todos/ - Todo lists and session state
• Any other persistent user data

Cache ($XDG_CACHE_HOME/claude/ or ~/.cache/claude/)

• statsig/ - Analytics and feature flag cache
• Any other non-essential cached data

Benefits

1. Standards Compliance: Follows established Unix/Linux conventions
2. Better Organization: Clear separation between config, data, and cache
3. Easier Backup: Users can backup config and data while excluding cache
4. System Integration: Works better with backup tools, dotfile managers, and system cleaners
5. User Expectations: Power users expect tools to follow XDG spec
6. Flexibility: Respects user's XDG environment variables if set

Implementation Proposal

I'm willing to help implement these changes. The implementation could:

1. Check for XDG environment variables and use them if set
2. Fall back to default XDG locations if not set
3. Include a migration path for existing installations
4. Maintain backward compatibility during a transition period

Migration Strategy

1. On first run after update, check if old locations exist
2. If found, offer to migrate files to new XDG-compliant locations
3. Optionally maintain symlinks for a few versions for compatibility

Additional Considerations

• Could also move ~/.claude/CLAUDE.md to $XDG_CONFIG_HOME/claude/CLAUDE.md for consistency
• The ~/.claude/ directory could be deprecated in favor of full XDG compliance

Would the team be interested in this improvement? I'd be happy to contribute to the implementation.