ADR-0002

accepted

Adopt XDG Base Directory specification for path management

2026-02-21

Context

All klaudiush file paths were hardcoded to ~/.klaudiush/ or ~/.claude/hooks/. Each component (exceptions, crashdump, patterns, plugins) had its own tilde expansion code - five duplicate implementations across the codebase with no single place managing paths.

The XDG Base Directory Specification is the standard convention for organizing user-level files by purpose (config vs data vs state vs cache). Most CLI tools on Linux and macOS follow it.

Decision

Adopt XDG with automatic migration from legacy paths. A new internal/xdg/ package becomes the single source of truth for every path klaudiush touches on disk.

XDG var	Default	klaudiush subdir
`XDG_CONFIG_HOME`	`~/.config`	`klaudiush/`
`XDG_DATA_HOME`	`~/.local/share`	`klaudiush/`
`XDG_STATE_HOME`	`~/.local/state`	`klaudiush/`

On first run after upgrade, klaudiush detects ~/.klaudiush/, moves files to their XDG locations, and leaves symlinks at the legacy paths for backward compatibility. Migration is idempotent.

xdg.ResolveFile(xdgPath, legacyPath) checks the XDG location first and falls back to the legacy path if the file exists only there. New files always go to XDG paths.

Consequences

Five tilde expansion implementations replaced by one package. XDG env vars (XDG_CONFIG_HOME, etc.) work as expected. KLAUDIUSH_LOG_FILE added for custom log location. klaudiush doctor --category xdg detects and fixes path issues.

Symlinks remain at legacy locations after migration. Users who scripted against ~/.klaudiush/ paths need to update - symlinks cover config and log, but not all paths.