Skip to content

Refactor Claude Code config to use individual file symlinks #66

@ikuwow

Description

@ikuwow

Problem

The current approach of symlinking the entire claude-user-config directory has several issues:

  1. Claude Code creates ~/.claude/ as a real directory first, preventing the symlink from being created
  2. Relative path symlinks (e.g., CLAUDE.md -> ../AIRULES.md) break after deployment
  3. The .gitignore becomes complex due to excluding Claude Code's dynamic files

Solution

Replace the directory-level symlink with individual file symlinks.

New Directory Structure

~/dotfiles/
  AIRULES.md              # Common AI rules (existing)
  rules/                  # Rules directory (existing)
  claude/                 # Renamed from claude-user-config
    .mcp.json             # MCP server configuration
    settings.json         # Claude Code settings

deploy.sh Changes

# Claude Code settings
mkdir -p "$HOME/.claude"
ln -fvns "$DOTPATH/claude/.mcp.json" "$HOME/.claude/.mcp.json"
ln -fvns "$DOTPATH/claude/settings.json" "$HOME/.claude/settings.json"
ln -fvns "$DOTPATH/AIRULES.md" "$HOME/.claude/CLAUDE.md"
ln -fvns "$DOTPATH/rules" "$HOME/.claude/rules"

Benefits

  • No more .gitignore needed (dynamic files stay in untracked ~/.claude/)
  • No more relative path issues (using absolute paths for symlinks)
  • Works even when Claude Code creates the directory first
  • Simpler structure

Implementation Steps

  1. Rename claude-user-config/ to claude/
  2. Remove claude/CLAUDE.md symlink
  3. Remove claude/rules symlink
  4. Remove claude/.gitignore
  5. Update deploy.sh with individual file symlinks
  6. Run deploy.sh and verify
  7. Remove ~/AIRULES.md (stray file created by broken symlink)

Verification

# Check symlinks
ls -la ~/.claude/CLAUDE.md
ls -la ~/.claude/rules
ls -la ~/.claude/.mcp.json
ls -la ~/.claude/settings.json

# Verify targets
readlink ~/.claude/CLAUDE.md  # -> /Users/ikuwow/dotfiles/AIRULES.md
readlink ~/.claude/rules      # -> /Users/ikuwow/dotfiles/rules

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions