About dot-claude-sync
TL;DR
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:
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!
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
Go install:
go install github.com/yugo-ibuki/dot-claude-sync@latest
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
This command performs initial setup interactively:
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
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
This command:
4. Verify Configuration
dot-claude-sync list
View current configuration. Displays group names and their project paths.
5. Execute Sync
dot-claude-sync push my-app
Syncs .claude directories across all projects in the specified group.
Safe execution (dry-run mode):
dot-claude-sync push my-app --dry-run
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)
When you run dot-claude-sync push my-app with this config:
Key Features
🔍 detect - Auto-detect worktrees
dot-claude-sync detect ~/projects/my-app --group my-app
In git worktree environments, bulk add .claude directories from multiple worktrees to the config file.
What it does:
Benefits:
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
Use cases:
📤 push - Execute sync
dot-claude-sync push my-app
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
Deletes specified files from all projects in the group.
📝 mv - Bulk rename
dot-claude-sync mv my-app old-name.md new-name.md
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
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
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
# Distribute shared project config to all projects
dot-claude-sync push web-projects
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
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:
If this interests you, please give it a try!
Links
More...
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!
- 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
Go install:
go install github.com/yugo-ibuki/dot-claude-sync@latest
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
This command performs initial setup interactively:
- Enter group name: Choose a name for your project group (e.g., my-app, web-projects)
- 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
- 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
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
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
View current configuration. Displays group names and their project paths.
5. Execute Sync
dot-claude-sync push my-app
Syncs .claude directories across all projects in the specified group.
Safe execution (dry-run mode):
dot-claude-sync push my-app --dry-run
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)
When you run dot-claude-sync push my-app with this config:
- Collect files from all projects' .claude directories
- If filenames conflict, use the file from the higher priority project (main)
- Distribute collected files to all projects
Key Features
🔍 detect - Auto-detect worktrees
dot-claude-sync detect ~/projects/my-app --group my-app
In git worktree environments, bulk add .claude directories from multiple worktrees to the config file.
What it does:
- Executes git worktree list in the specified directory
- Checks if .claude directory exists in each detected worktree path
- If it exists, automatically adds to config file (~/.config/dot-claude-sync/config.yaml)
- 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
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
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
Deletes specified files from all projects in the group.
📝 mv - Bulk rename
dot-claude-sync mv my-app old-name.md new-name.md
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
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
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
# Distribute shared project config to all projects
dot-claude-sync push web-projects
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
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
- GitHub: https://github.com/yugo-ibuki/dot-claude-sync
- Installation:
- Homebrew: brew install dot-claude-sync
- Go install: go install github.com/yugo-ibuki/dot-claude-sync@latest
More...