DEV Community

Ugo
Ugo

Posted on

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

#ai #tooling #claude #document

About dot-claude-sync

TL;DR

  • A Go CLI tool that synchronizes .claude directories across multiple projects/worktrees
  • Achieves flexible synchronization strategies through group management and priority system
  • Dramatically improves Claude Code utilization in git worktree environments

Introduction

My workflow involves having Claude Code first conduct research and create TODOs for tasks, which I then review before having it write the code.
During this process, I want these documents created within the project itself so I don't have to open a separate editor to view them.

However, they always show up as Git diffs, and adding them to global ignore is cumbersome.
Placing them at the root risks Claude recognizing them, potentially mixing in unnecessary prompts.
That's when I focused on the .claude folder, which Claude doesn't automatically read.

I thought placing documents in .claude would make management easier, and it worked well in practice.
For example, when working on a dashboard fix task, I create a folder like dashboard-fix-XXX inside .claude/custom-documents to consolidate task-related content.

As I use Claude Code, I increasingly save useful prompts, skills, and project context in the .claude directory.

However, when developing multiple branches simultaneously with git worktree, .claude is gitignored and doesn't sync across worktrees.

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

Background and Challenges

Utilizing .claude with Claude Code

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

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

By not managing these with git (gitignore), you can use them as Claude-specific long-term context without polluting the repository.

While you can share them with your team, individual document quality varies, and they tend to accumulate without organization, causing unnecessary context pollution.

By managing personal items individually and sharing desired content like skills through Plugins on the marketplace, you can share cleanly.

Challenges with git worktree

Issues arise in development workflows using git worktree:

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 synced at creation, .claude contents aren't shared across worktrees as you use them
  • Separate configuration needed for each worktree
  • Manual copying of useful prompts required each time

dot-claude-sync's Solution

dot-claude-sync groups projects using the concept of "groups" and controls synchronization strategy with a priority system.

Basic Usage

1. Installation

Homebrew (recommended):

brew install dot-claude-sync
Enter fullscreen mode Exit fullscreen mode

Go install:

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

After installation, the dot-claude-sync command becomes available.

:::message
For Go install, $GOPATH/bin (typically ~/go/bin) must be in your PATH.
:::

2. Initial Setup (Interactive) 

dot-claude-sync init
Enter fullscreen mode Exit fullscreen mode

This command performs initial setup interactively:

  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 you want to sync
    • Multiple paths can be entered (empty line to finish)
    • Relative paths using ~ are 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]

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

3. Auto-detect worktrees (Optional)

Instead of manually entering paths, use the detect command to auto-detect worktrees:

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

This command:

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

4. Verify Configuration 

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

View current configuration. Displays group names and their project paths.

5. Execute Sync 

dot-claude-sync 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
Enter fullscreen mode Exit fullscreen mode

Preview what will happen without actually copying files. Using --dry-run is recommended for initial execution.

Config 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  # main has highest priority (master config)
Enter fullscreen mode Exit fullscreen mode

When you run dot-claude-sync push my-app with this config:

  1. Collect files from all projects' .claude directories
  2. If filenames conflict, use the file from the higher priority project (main)
  3. Distribute collected files to all projects

Key Features

🔍 detect - Auto-detect worktrees 

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

In git worktree environments, bulk add .claude directories from multiple worktrees to the config file.

What it does:

  1. Executes git worktree list in the specified directory
  2. Checks if .claude directory exists in each detected worktree path
  3. If it exists, automatically adds to config file (~/.config/dot-claude-sync/config.yaml)
  4. Uses worktree branch names as aliases (e.g., main, feature-a)

Benefits:

  • Eliminates manual path entry for each worktree
  • Quick response to worktree configuration changes (additions/deletions)
  • Reduces risk of typos and path errors

Example execution:

# Detect worktrees in ~/projects/my-app and add to my-app group
dot-claude-sync detect ~/projects/my-app --group my-app

# After execution, config.yaml is automatically updated like this:
# 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:

  • Quickly complete worktree environment setup for new projects
  • Update configuration when adding new worktrees to existing projects
  • Easy reproduction of the same worktree configuration for team members

📤 push - Execute sync 

dot-claude-sync push my-app
Enter fullscreen mode Exit fullscreen mode

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

🗑️ rm - Bulk delete 

dot-claude-sync rm my-app prompts/old-prompt.md
Enter fullscreen mode Exit fullscreen mode

Deletes specified files from all projects in the group.

📝 mv - Bulk rename 

dot-claude-sync mv my-app old-name.md new-name.md
Enter fullscreen mode Exit fullscreen mode

Renames/moves files across all projects in the group.

⚙️ config - Configuration management 

# Add group
dot-claude-sync config add-group new-group

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

# Set priority
dot-claude-sync 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.

Use Cases

Case 1: Instant worktree environment setup 

# Auto-detect and add .claude directories in worktree project
dot-claude-sync detect ~/projects/my-app --group my-app

# Start syncing immediately
dot-claude-sync push my-app
Enter fullscreen mode Exit fullscreen mode

Case 2: Distribute common configuration 

groups:
  web-projects:
    paths:
      shared: ~/projects/shared-config/.claude  # Common config master
      frontend: ~/projects/frontend/.claude
      backend: ~/projects/backend/.claude
    priority:
      - shared  # shared has highest priority
Enter fullscreen mode Exit fullscreen mode 
# Distribute shared project config to all projects
dot-claude-sync 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 configuration to each client project.

Summary

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

Recommended for:

  • Users leveraging git worktree
  • Those wanting to use common .claude configuration across multiple projects
  • Anyone looking to streamline prompt and skill management

If this interests you, please give it a try!

Links

Top comments (0)