Cross-platform CLI tool to sync Claude Code chat sessions to your project directory

中文文档 | English

IMPORTANT: Do NOT commit .claudeCodeSessions/ to your repository unless absolutely necessary!

Session files may contain sensitive information:

• API keys and authentication tokens - Can be used to access your account
• Proprietary code and business logic - Your confidential code and algorithms
• Private conversations - Internal discussions and sensitive topics
• System paths and environment details - Information about your infrastructure

Keep .claudeCodeSessions/ in your .gitignore

This is the safest option. After running claude-chats-sync init, the tool automatically adds the following entries to .gitignore:

# Claude Code conversation history
.claudeCodeSessions/
.claudeCodeSessions/**/sessions-index.json
tmpclaude*

These entries are active (not commented) by default to ensure session files and temporary files are ignored by Git.

1. Use environment variables for API keys - This prevents them from appearing in session files
2. Use the Git filter - Automatically cleans API keys on commit (but not 100% reliable)
3. Review files before committing - Manually check for any sensitive data
4. Understand the risks - No automated cleaning is 100% complete

You are responsible for ensuring no sensitive data is committed.

• 🔄 Auto-sync - Creates symlinks from Claude Code local storage to your project folder
• 📁 Project-local history - Chat sessions stored in your project, not user home directory
• 🔒 Sensitive data protection - Cleans API keys from session files
• 🎯 Simple to use - Initialize sync with a single command
• 📊 Status tracking - Check sync status and session count
• 🌳 Git-friendly - Configure Git filters for safe version control
• 🔧 Cross-platform - Works on Windows, macOS, and Linux

npm install -g claude-chats-sync

This allows you to use claude-chats-sync command from anywhere.

npm install -D claude-chats-sync

Then use it via npx:

npx claude-chats-sync init

# In your project directory
claude-chats-sync init

This will:

• Create a .claudeCodeSessions/ folder in your project
• Create a symlink in ~/.claude/projects/
• Configure Git filter for automatic sensitive data cleaning
• Add .claudeCodeSessions/ and related patterns to .gitignore
• Display security warnings and best practices

claude-chats-sync status

claude-chats-sync open

# Initialize sync
claude-chats-sync init

# Check status
claude-chats-sync status

# Open sessions folder
claude-chats-sync open

# Custom folder name
claude-chats-sync init --folder-name .sessions

# Force migrate existing sessions
claude-chats-sync init --force

# Specify project path
claude-chats-sync init --project-path /path/to/project

# Manual cleanup
claude-chats-sync clean

# Setup Git auto-filter
claude-chats-sync setup-git-filter

# Update Git filter (for existing projects)
claude-chats-sync update

Note: If you initialized your project with an older version (before v0.0.8), run claude-chats-sync update to get the latest Git filter features including path cleaning and smudge filter.

Configure API keys via environment variables to prevent them from appearing in session files:

Linux/macOS - Add to ~/.bashrc or ~/.zshrc:

export ANTHROPIC_AUTH_TOKEN="sk-ant-..."
export ANTHROPIC_BASE_URL="https://api.example.com"  # Optional: for third-party API

Windows PowerShell:

$env:ANTHROPIC_AUTH_TOKEN="sk-ant-..."
$env:ANTHROPIC_BASE_URL="https://api.example.com"

Windows CMD (permanent):

setx ANTHROPIC_AUTH_TOKEN "sk-ant-..."
setx ANTHROPIC_BASE_URL "https://api.example.com"

Option 1: Use environment variables (Recommended)

Configure Claude Code to use API keys from environment variables. This prevents them from appearing in session files entirely.

Option 2: Use Git filter

If you store API keys in config files, the Git filter automatically cleans them on commit.

After initialization, commit normally:

git add .claudeCodeSessions/
git commit -m "Add conversation history"

# API keys are automatically replaced with [REDACTED]
# Your local files remain unchanged

RECOMMENDED: Ignore session files entirely. Uncomment in .gitignore:

.claudeCodeSessions/

This prevents accidentally committing sensitive data to your repository.

Claude Code stores chat sessions in ~/.claude/projects/{normalized-project-path}/.

This CLI creates a symbolic link to a folder in your project (default: .claudeCodeSessions/), making the chat history part of your project.

Your Project/
├── src/
├── .claudeCodeSessions/      # Chat sessions (synced with ~/.claude)
│   ├── session-abc123.jsonl
│   └── session-def456.jsonl
├── .gitignore               # Auto-updated
├── .gitattributes           # Git filter configuration
└── package.json

If you choose to sync session files:

1. Commit the .claudeCodeSessions/ folder
2. Push to GitHub
3. Pull on another machine
4. Run claude-chats-sync init to create the symlink

• Uses junction points (no admin privileges required)
• Supports PowerShell and CMD
• Run PowerShell scripts may require: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

• Requires execute permissions: chmod +x $(which claude-chats-sync)
• Uses standard symbolic links

• Requires execute permissions: chmod +x $(which claude-chats-sync)
• Uses standard symbolic links

The tool uses junction points which work without admin privileges. If issues persist:

• Ensure Node.js is in your PATH
• Try running as administrator
• Check that your project path doesn't contain special characters

1. Check if symlink exists:

   • Windows: dir %USERPROFILE%\.claude\projects
   • macOS/Linux: ls -la ~/.claude/projects

2. Verify symlink points to your project's .claudeCodeSessions/ folder

Delete existing symlink:

# Windows
rmdir "%USERPROFILE%\.claude\projects\{project-name}"

# macOS/Linux
rm ~/.claude/projects/{project-name}

Then run claude-chats-sync init again.

• VSCode Extension - Full-featured VSCode extension with the same functionality

⚠️ IMPORTANT: When sharing session files, each team member uses their own API key and incurs their own API costs.

1. Each member pays for their own usage

   • Every team member must configure their own API key
   • When you continue a shared conversation, you pay for all new tokens generated
   • The original creator's API key is never used

2. Context window considerations

   • Long shared conversations consume more tokens as context
   • A shared conversation with 50,000 tokens will consume ~50,000 input tokens each time a new member continues it

3. Cost-saving best practices

   • Generate conversation summaries before sharing
   • Start new conversations when possible
   • Archive old sessions
   • Monitor your API usage

For detailed cost considerations, see Token Usage Guide.

MIT - see LICENSE file for details

Contributions are welcome! Please open an issue or submit a pull request.

• 📧 Issues
• 📖 Documentation
• 💬 Discussions

• npm
• GitHub
• VSCode Marketplace

Made with ❤️ by tubo70