Share Claude-created Documents Across Worktrees with dot-claude-sync
#ai#tooling#claude#document
Ugo

Ugo @ugo

About: AI Application Engineer in Japan

Location:
Japan
Joined:
Jul 25, 2021

Share Claude-created Documents Across Worktrees with dot-claude-sync

Publish Date: Nov 16
0 0

About dot-claude-sync

TL;DR

  • A Go-based CLI tool to synchronize .claude directories across multiple projects/worktrees
  • Flexible sync strategies with group management and priority system
  • Dramatically improves Claude Code workflow in git worktree environments

Introduction

My workflow with Claude Code involves having it create investigation documents and TODO lists first, which I then review before having it write code. I want these documents to be within the project so I don't have to open a separate editor to view them.

However, placing them in the project root causes them to appear in git diffs, and setting up global ignore is cumbersome. Additionally, placing them at the root risks polluting Claude's context with unnecessary prompts. That's when I discovered the .claude folder - a directory that Claude doesn't automatically read.

I tried organizing documents in .claude and found it worked well. For example, when fixing a dashboard, I create a folder like .claude/custom-documents/dashboard-fix-XXX to consolidate all task-related content there.

When working with Claude Code, you often save useful prompts, skills, and project context in the .claude directory.

However, when developing with git worktrees across multiple branches, .claude isn't synced between worktrees since it's gitignored.

dot-claude-sync was developed to solve this problem.

Background and Challenges

Using .claude with Claude Code

When developing with Claude Code, it's useful to save the following in the .claude directory as documentation:

  • Task-specific prompts
  • Frequently used skills and commands
  • Implementation specifications and TODO lists
  • Project context information

These are not managed by git (gitignored), allowing you to maintain Claude-specific long-term context without polluting the repository.

While you can share with your team, individual documentation quality varies, and unorganized growth leads to context pollution.

Therefore, it's better to manage personal documents individually and share skills through Plugins on the marketplace.

Git Worktree Challenges

Issues arise when using git worktrees:

my-project/
├── main/           # Main worktree
│   └── .claude/
│       └── prompts/useful-prompt.md
├── feature-a/      # feature-a worktree
│   └── .claude/    # Empty!
└── feature-b/      # feature-b worktree
    └── .claude/    # Empty!
Enter fullscreen mode Exit fullscreen mode
  • Even if initially synced, .claude contents diverge as you work across worktrees
  • Each worktree requires separate setup
  • Manual copying of useful prompts between worktrees

dot-claude-sync Solution

dot-claude-sync manages projects through groups and controls sync strategy with a priority system.

Basic Usage

1. Installation

Go install:

go install github.com/yugo-ibuki/dot-claude-sync@latest
Enter fullscreen mode Exit fullscreen mode

Short alias version (dcs command) also available:

go install github.com/yugo-ibuki/dot-claude-sync/cmd/dcs@latest
Enter fullscreen mode Exit fullscreen mode

After installation, you can use the dot-claude-sync command (or dcs).

:::message
$GOPATH/bin (usually ~/go/bin) must be in your PATH.
:::

Build from source:

git clone https://github.com/yugo-ibuki/dot-claude-sync.git
cd dot-claude-sync
go build                    # Generates dot-claude-sync binary
go build -o dcs ./cmd/dcs   # Generates dcs alias binary
Enter fullscreen mode Exit fullscreen mode

2. Initial Setup (Interactive) 

dot-claude-sync init
# or short version
dcs init
Enter fullscreen mode Exit fullscreen mode

Running this command starts an interactive setup:

  1. Enter group name: Choose a name for your project group (e.g., my-app, web-projects)
  2. Enter project paths: Input paths to .claude directories to sync
    • Multiple paths supported (empty line to finish)
    • Relative paths with ~ supported
  3. Auto-create config file: Creates ~/.config/dot-claude-sync/config.yaml

Example execution:

$ dot-claude-sync init
Enter group name: my-app
Enter project paths (empty line to finish):
Path 1: ~/projects/my-app/main/.claude
Path 2: ~/projects/my-app/feature-a/.claude
Path 3: ~/projects/my-app/feature-b/.claude
Path 4: [Enter]

Configuration file created: ~/.config/dot-claude-sync/config.yaml
Enter fullscreen mode Exit fullscreen mode

3. Auto-detect Worktrees (Optional)

Instead of manual path entry, use the detect command to auto-detect worktrees:

dot-claude-sync detect ~/projects/my-app --group my-app
# or
dcs detect ~/projects/my-app --group my-app
Enter fullscreen mode Exit fullscreen mode

This command:

  • Runs git worktree list to detect worktrees
  • Checks if .claude directory exists in each worktree
  • Automatically adds to config file if found

4. View Configuration 

dot-claude-sync list
# or
dcs list
Enter fullscreen mode Exit fullscreen mode

View current configuration showing group names and project paths.

5. Run Sync 

dot-claude-sync push my-app
# or
dcs push my-app
Enter fullscreen mode Exit fullscreen mode

Syncs .claude directories across all projects in the specified group.

Safe execution (dry-run mode):

dot-claude-sync push my-app --dry-run
# or
dcs push my-app --dry-run
Enter fullscreen mode Exit fullscreen mode

Previews what will happen without actually copying files. Recommended for first run with --dry-run.

Configuration File Example

~/.config/dot-claude-sync/config.yaml:

groups:
  my-app:
    paths:
      main: ~/projects/my-app/main/.claude
      feature-a: ~/projects/my-app/feature-a/.claude
      feature-b: ~/projects/my-app/feature-b/.claude
    priority:
      - main  # Highest priority (master configuration)
Enter fullscreen mode Exit fullscreen mode

Running dot-claude-sync push my-app with this configuration:

  1. Collects files from all project .claude directories
  2. When duplicate filenames exist, uses file from highest priority project (main)
  3. Distributes collected files to all projects

Key Features

🔍 detect - Auto-detect Worktrees 

dot-claude-sync detect ~/projects/my-app --group my-app
# or
dcs detect ~/projects/my-app --group my-app
Enter fullscreen mode Exit fullscreen mode

Batch adds multiple worktree .claude directories to configuration in git worktree environments.

What it does:

  1. Runs git worktree list in specified directory
  2. Checks if .claude directory exists in each detected worktree
  3. Automatically adds to config file (~/.config/dot-claude-sync/config.yaml) if found
  4. Uses worktree branch name as alias (e.g., main, feature-a)

Benefits:

  • No manual entry of worktree paths
  • Quick response to worktree configuration changes (add/remove)
  • Reduces typo and path error risks

Example execution:

# Detect worktrees in ~/projects/my-app and add to my-app group
dcs detect ~/projects/my-app --group my-app

# After execution, config.yaml is auto-updated:
# groups:
#   my-app:
#     paths:
#       main: ~/projects/my-app/main/.claude
#       feature-a: ~/projects/my-app/feature-a/.claude
#       feature-b: ~/projects/my-app/feature-b/.claude
Enter fullscreen mode Exit fullscreen mode

Use cases:

  • Quick setup of worktree environment in new project
  • Update configuration when adding new worktree to existing project
  • Easy reproduction of same worktree structure by team members

📤 push - Run Sync 

dcs push my-app
Enter fullscreen mode Exit fullscreen mode

Collects .claude files from all projects in group and distributes based on priority.

💾 backup - Create Backup 

dcs backup my-app
Enter fullscreen mode Exit fullscreen mode

Creates timestamped backups of .claude directories for all projects in group.
Backups are saved to ~/.local/share/dot-claude-sync/backups/.

Use cases:

  • Safety before first sync
  • Protection before major changes
  • Regular backup operations

🗑️ rm - Batch Delete 

dcs rm my-app prompts/old-prompt.md
Enter fullscreen mode Exit fullscreen mode

Deletes specified file from all projects in group.

📝 mv - Batch Rename 

dcs mv my-app old-name.md new-name.md
Enter fullscreen mode Exit fullscreen mode

Renames/moves files in all projects in group.

⚙️ config - Configuration Management 

# Add group
dcs config add-group new-group

# Add project
dcs config add-project my-app feature-c ~/projects/my-app/feature-c/.claude

# Set priority
dcs config set-priority my-app main feature-a feature-b feature-c
Enter fullscreen mode Exit fullscreen mode

Edit configuration file directly from command line.

Command Aliases

dot-claude-sync and dcs provide identical functionality. Both aliases work for all commands:

# These work exactly the same
dot-claude-sync init
dcs init

dot-claude-sync push my-app
dcs push my-app

dot-claude-sync list
dcs list
Enter fullscreen mode Exit fullscreen mode

dcs is recommended for daily use due to its shorter length.

Use Cases

Case 1: Quick Worktree Environment Setup 

# Auto-detect and add worktree .claude directories
dcs detect ~/projects/my-app --group my-app

# Create backup (for safety)
dcs backup my-app

# Start syncing immediately
dcs push my-app
Enter fullscreen mode Exit fullscreen mode

Case 2: Distribute Shared Configuration 

groups:
  web-projects:
    paths:
      shared: ~/projects/shared-config/.claude  # Shared config master
      frontend: ~/projects/frontend/.claude
      backend: ~/projects/backend/.claude
    priority:
      - shared  # Highest priority
Enter fullscreen mode Exit fullscreen mode 
# Distribute shared project settings to all projects
dcs push web-projects
Enter fullscreen mode Exit fullscreen mode

Case 3: Client Project Template Management 

groups:
  clients:
    paths:
      template: ~/templates/client/.claude
      client-a: ~/clients/a/.claude
      client-b: ~/clients/b/.claude
    priority:
      - template
Enter fullscreen mode Exit fullscreen mode

Deploy template project settings to each client project.

Global Options

All commands support the following options:

--config <path>   # Specify configuration file path
--dry-run         # Preview execution (no actual changes)
--verbose         # Output detailed logs
--force           # Skip confirmation prompts
Enter fullscreen mode Exit fullscreen mode

Usage examples:

# Safe confirmation with dry-run
dcs push my-app --dry-run

# Execute with detailed logs
dcs push my-app --verbose

# Use custom configuration file
dcs push my-app --config ~/custom-config.yaml
Enter fullscreen mode Exit fullscreen mode

Summary

dot-claude-sync is a small tool that improves Claude Code workflow in git worktree environments.

Recommended for:

  • Users working with git worktrees
  • Those wanting shared .claude settings across multiple projects
  • Anyone looking to streamline prompt and skill management

If you're interested, please give it a try!

Links

Comments 0 total

    Add comment