VS Code Extension: Lacks XDG Base Directory Specification Compliance

[alexgmathews]

VS Code Extension: Lacks XDG Base Directory Specification Compliance

Environment Information

System Configuration

• Operating System: Linux Mint 22.2
• Kernel: Linux 6.8.0-59-generic
• Architecture: x64

Software Versions

• VS Code: 1.107.0 (commit: 618725e67565b290ba4da6fe2d29f8fa1d4e3622)
• Claude Code VS Code Extension: [email protected]
• Claude Code CLI: 2.0.60

User Environment Configuration

XDG Base Directory variables (explicitly set):

XDG_RUNTIME_DIR=/run/user/1000
XDG_CONFIG_HOME=$HOME/.config
XDG_DATA_HOME=$HOME/.local/share
XDG_STATE_HOME=$HOME/.local/state
XDG_CACHE_HOME=$HOME/.cache

Claude Code configuration (explicitly set):

CLAUDE_CONFIG_DIR=$HOME/.config/claude

---

Issue Summary

The Claude Code VS Code extension does not follow the XDG Base Directory Specification, instead hardcoding ephemeral IPC lock files to ~/.claude/ide/. This violates Linux/freedesktop standards that XDG-compliant software should follow automatically, regardless of whether environment variables are explicitly set.

Primary Issue: Extension lacks XDG Base Directory compliance entirely Secondary Issue: Even when XDG environment variables are explicitly configured, they are ignored

The Core Problem

What XDG Compliance Means

XDG-compliant software should automatically follow the XDG Base Directory Specification by:

1. Using standard default locations (e.g., /run/user/$UID for runtime files)
2. Respecting XDG environment variables when explicitly set
3. Never hardcoding paths in user home directories

The specification defines these directories with built-in defaults:

• $XDG_RUNTIME_DIR: Runtime/ephemeral state (default: /run/user/$UID on Linux)
• $XDG_CONFIG_HOME: User configuration (default: ~/.config)
• $XDG_DATA_HOME: User data (default: ~/.local/share)
• $XDG_STATE_HOME: User state (default: ~/.local/state)

Compliant software should work correctly even without explicitly set environment variables.

Evidence of Non-Compliance

To demonstrate the severity of this issue, the reporter explicitly configured XDG variables:

CLAUDE_CONFIG_DIR=$HOME/.config/claude
XDG_RUNTIME_DIR=/run/user/1000
XDG_CONFIG_HOME=$HOME/.config
XDG_DATA_HOME=$HOME/.local/share
XDG_STATE_HOME=$HOME/.local/state

Result: Extension still ignores all XDG variables and creates ~/.claude/ide/ with hardcoded path

This demonstrates the extension has no XDG implementation whatsoever, not even basic environment variable checking

Current Behavior

When VS Code launches with Claude Code extension enabled:

1. Extension creates ~/.claude/ide/ directory (hardcoded path, no env var checks)
2. Generates ephemeral lock files: <pid>.lock
3. Lock files contain JSON with temporary session state:
   • Process ID of VS Code instance
   • Workspace folder paths
   • IDE name and transport protocol
   • Authentication tokens
   • Platform information

The Problem

1. No XDG Base Directory Compliance (Primary Issue)

The extension hardcodes ~/.claude/ide/ instead of implementing XDG Base Directory Specification support. The XDG specification (https://specifications.freedesktop.org/basedir-spec/) defines:

• $XDG_RUNTIME_DIR: "For ephemeral session state. Must not contain links to other files, and the files in it MUST NOT persist after a logout."
  • Default on Linux: /run/user/$UID (when env var not set)
  • Extension behavior: Ignores this entirely, uses hardcoded ~/.claude/ide/

The Critical Violation: XDG-compliant software should work correctly by default, using standard XDG locations even when environment variables are not explicitly set. The extension fails this fundamental requirement by hardcoding home directory paths.

Current violation:

• Lock files are ephemeral runtime state (PIDs, auth tokens)
• Placed in ~/.claude/ide/ which persists after logout
• Should be in /run/user/$UID/claude/ide/ by default on Linux
• Should respect $XDG_RUNTIME_DIR when explicitly set

2. Ignores Explicit Environment Configuration (Secondary Issue)

Even when user explicitly configures XDG environment variables (as demonstration), extension ignores them:

• User set CLAUDE_CONFIG_DIR=$HOME/.config/claude → Extension ignores it
• User set XDG_RUNTIME_DIR=/run/user/1000 → Extension ignores it
• Extension creates ~/.claude/ directory anyway (polluting home directory)

This contradicts Claude's own documented behavior where CLI respects CLAUDE_CONFIG_DIR.

3. Non-Portable and Non-Standard (Ecosystem Impact)

Creates unnecessary home directory structure that:

• Breaks dotfile management and backup tools
• Complicates system migration and cleanup
• Violates portability assumptions of XDG-compliant systems
• Conflicts with user's intentional directory organization

Impact on User's System

User's intentional directory layout:

~/.config/                              # XDG_CONFIG_HOME
  └── claude/                           # CLAUDE_CONFIG_DIR
      ├── CLAUDE.md                     # User global config
      └── shell-snapshots/              # Legitimate state

~/.local/                               # XDG_DATA_HOME prefix
  ├── share/                            # XDG_DATA_HOME
  ├── state/                            # XDG_STATE_HOME
  └── cache/                            # XDG_CACHE_HOME

/run/user/1000/                         # XDG_RUNTIME_DIR
  # (Extension lock files should go here)

Actual behavior: Creates polluting ~/.claude/ide/ outside configured structure

Technical Details

Why This Matters

1. Session managers clean $XDG_RUNTIME_DIR at logout; home directory is permanent
2. Backup tools should not include temporary state from home directory
3. Portable systems expect home directory to be minimal and configured
4. Standards compliance is critical for ecosystem interoperability

Proposed Solution

The extension should place ephemeral IPC lock files in platform-appropriate runtime directories that follow XDG Base Directory Specification conventions:

*Linux (nix systems):

• Respect $XDG_RUNTIME_DIR if explicitly set
• Default to /run/user/$UID/ following XDG specification
• Do not hardcode ~/.claude/ide/

macOS:

• Consider XDG conventions often ported/followed by *nix tools
• Research macOS-native ephemeral storage conventions

Windows:

• Research Windows-appropriate locations for ephemeral state
• Note: XDG Base Directory Specification does NOT apply to Windows

Related Standards and References

• XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• Freedesktop.org directory structure: https://specifications.freedesktop.org/
• Session directory cleanup: https://man7.org/linux/man-pages/man7/xdg-basedir-implementation-notes.7.html

File Locations Involved

• Extension file: anthropic.claude-code VS Code extension
• Affected path: ~/.claude/ide/ (should be $XDG_RUNTIME_DIR/claude/ide/)
• Related config: ~/.config/claude/ (correctly respects CLAUDE_CONFIG_DIR)
• Related CLI: Claude Code CLI (respects config env vars, extension should too)

[github-actions[bot]]

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/1455
2. https://github.com/anthropics/claude-code/issues/11794
3. https://github.com/anthropics/claude-code/issues/2350

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[alexgmathews]

This is NOT a duplicate.

The referenced issues (#1455, #11794, #2350) are about Claude Code CLI.

This issue is specifically about the VS Code extension (anthropic.claude-code). It was reported here because there is no separate repository for VS Code extension bugs.

Component affected: anthropic.claude-code VS Code extension only