Feature Request: XDG Base Directory Compliance and Configurable Settings Storage

Feature Request: XDG Base Directory Compliance and Configurable Settings Storage

Summary

Claude Code currently stores configuration files (~/.claude.json) and backup files (~/.claude.json.backup.*) in the user's home directory, which creates clutter and doesn't follow XDG Base Directory conventions. Request ability to configure storage location and control backup behavior.

Current Behavior

• Settings stored in ~/.claude.json (home directory root)
• Automatic backups create ~/.claude.json.backup.<timestamp> files
• Multiple backup files accumulate in home directory
• No way to configure storage location
• No way to disable or limit backup creation

Proposed Changes

1. XDG Base Directory Compliance (Primary Request)

Follow the XDG Base Directory Specification:

Current:

~/.claude.json
~/.claude.json.backup.1769889128296
~/.claude.json.backup.1769894997427

Proposed:

~/.config/claude/settings.json
~/.config/claude/backups/settings.json.1769889128296
~/.local/state/claude/session-state.json

2. Configurable Backup Behavior

Add settings to control backup creation:

{
  "backups": {
    "enabled": true,           // Disable backups entirely
    "maxCount": 5,             // Currently hardcoded at 5
    "location": "~/.config/claude/backups"
  }
}

3. Environment Variable Override

Allow XDG-compliant environment variable overrides:

export XDG_CONFIG_HOME=~/.config  # Config files
export XDG_STATE_HOME=~/.local/state  # Session state
export XDG_DATA_HOME=~/.local/share  # Application data

Benefits

1. Cleaner home directory - No configuration clutter in ~/
2. Platform conventions - Follows Unix/Linux best practices
3. Easier backup - Users can backup ~/.config/claude/ as a unit
4. Better organization - Separate config, state, and data
5. User control - Ability to disable backups or limit retention

Migration Strategy

To avoid breaking existing installations:

1. Check for files in new location first (~/.config/claude/)
2. Fall back to legacy location (~/.claude.json)
3. Provide migration command: claude migrate-config
4. Log deprecation warning when using legacy location

Use Cases

• Dotfiles management - Users managing dotfiles in git want clean home directories
• Containerized environments - Mounting specific config directories
• CI/CD pipelines - Predictable configuration locations
• Multi-user systems - Better separation of user configs

Similar Tools

Many CLI tools follow XDG conventions:

• gh (GitHub CLI): ~/.config/gh/
• nvim: ~/.config/nvim/
• docker: ~/.docker/config.json (older) → ~/.config/docker/ (newer)
• git: Supports $XDG_CONFIG_HOME/git/config

Platform Notes

• Linux/macOS: Use XDG directories (as above)
• Windows: Use %APPDATA%\Claude\ (already platform-appropriate)

References

• XDG Base Directory Spec: https://specifications.freedesktop.org/basedir-spec/latest/
• Current discussion: (user feedback showing demand for this)