PR Review: Fix XDG_CONFIG_HOME support for Claude config directory

Summary

This PR successfully addresses issue #242 by properly implementing XDG Base Directory specification support for Claude's configuration directory on Linux. The changes are well-structured, thoroughly tested, and maintain backward compatibility.

✅ Strengths

1. Clean Architecture

• The getClaudeConfigDir() function is well-designed with clear platform-specific logic
• Centralized configuration via RuntimeConfig.ClaudeConfigDir eliminates hardcoded paths throughout the codebase
• The new GetClaudeProjectsDir() helper method provides a clean abstraction

2. Excellent Test Coverage

• Unit tests in runtime_test.go cover all three scenarios:
  • Non-Linux systems using ~/.claude
  • Linux with XDG_CONFIG_HOME set
  • Linux without XDG_CONFIG_HOME (defaulting to ~/.config/claude)
• Tests properly use t.Setenv() for environment isolation

3. Comprehensive Migration

• All 14 files with hardcoded ~/.claude paths have been updated
• Consistent use of filepath.Join() for cross-platform compatibility
• Good documentation in comments explaining the XDG behavior

4. Code Quality

• Removal of deprecated claude_detector.go (231 lines) is excellent cleanup
• Comments are clear and helpful (e.g., container/internal/claude/paths/paths.go:27-30)
• Variable naming is consistent (claudeConfigDir throughout)

🔍 Issues & Concerns

1. Critical: Potential Race Condition in Runtime Initialization

In container/internal/claude/parser/history.go:25, the code directly accesses config.Runtime.ClaudeConfigDir:

func NewHistoryReader(homeDir string) *HistoryReader {
    claudeConfigDir := config.Runtime.ClaudeConfigDir  // Assumes Runtime is already initialized
    return &HistoryReader{
        claudeConfigPath: filepath.Join(homeDir, ".claude.json"),
        historyJSONLPath: filepath.Join(claudeConfigDir, "history.jsonl"),
    }
}

Issue: If config.Runtime hasn't been initialized when NewHistoryReader() is called, this will use an empty string or nil value, leading to incorrect paths.

Recommendation: Either:

• Document that config.Runtime must be initialized before calling these functions
• Add runtime initialization checks, or
• Pass claudeConfigDir as a parameter instead of relying on global state

This pattern appears in multiple files:

• container/internal/claude/parser/history.go:25
• container/internal/claude/paths/paths.go:33
• Several other locations

2. Inconsistency: Mixed Path Construction Approaches

In container/internal/handlers/pty.go:2259-2262:

transformedPath := strings.ReplaceAll(session.WorkDir, "/", "-")
transformedPath = strings.TrimPrefix(transformedPath, "-")
transformedPath = "-" + transformedPath
claudeProjectsDir := filepath.Join(config.Runtime.GetClaudeProjectsDir(), transformedPath)

Issue: This duplicates the path encoding logic instead of using the existing paths.EncodePathForClaude() function (defined in container/internal/claude/paths/paths.go:18).

Recommendation: Refactor to use the centralized encoding function to avoid logic drift.

3. Test Gap: XDG Environment Variable Persistence

The unit tests set XDG_CONFIG_HOME but don't verify that changes to the environment variable during runtime are properly handled.

Recommendation: Add a test that verifies the behavior when XDG_CONFIG_HOME changes between config initializations (if that's a supported scenario).

4. Documentation: Missing Migration Guide

Users running Catnip on Linux who already have configurations in ~/.claude won't automatically know:

• That their config location is changing
• Whether they need to manually migrate files
• How the system handles existing ~/.claude directories

Recommendation: Add a migration note in the PR description or a comment in the code explaining the transition path.

🔒 Security Review

✅ No security concerns identified

• No credential handling changes
• Path construction uses filepath.Join() (prevents path traversal)
• No user input is directly incorporated into file paths
• File permissions remain appropriate (0755 for directories)

⚡ Performance Considerations

✅ No performance issues

• getClaudeConfigDir() is called during initialization, not in hot paths
• The global config.Runtime pattern avoids repeated environment variable lookups
• File operations are unchanged from previous implementation

📋 Recommendations

Must Address:

1. Add runtime initialization safeguards or document the initialization order requirement for config.Runtime
2. Deduplicate path encoding logic by using paths.EncodePathForClaude() consistently

Should Address:
3. Add integration test or manual testing confirmation for XDG_CONFIG_HOME scenario
4. Add migration documentation for existing Linux users

Nice to Have:
5. Consider adding a runtime detection log message showing which Claude config directory is being used (helpful for debugging)
6. Add godoc examples for getClaudeConfigDir() and GetClaudeProjectsDir()

✅ Final Assessment

This is a well-executed PR that properly implements XDG Base Directory specification support. The code quality is high, test coverage is good, and the cleanup of deprecated code is appreciated.

The main concerns are around initialization order (potential for subtle bugs) and some minor code duplication. With those addressed, this will be a solid improvement to the codebase.

Recommendation: Request changes to address the runtime initialization pattern, then approve.

Great work on the thorough implementation and cleanup! 🎉

Codecov Report

❌ Patch coverage is 32.60870% with 31 lines in your changes missing coverage. Please review.

📢 Thoughts on this report? Let us know!