godlaugh/ClaudeSync

  .oooooo.   oooo                              .o8                .oooooo..o                                   
 d8P'  `Y8b  `888                             "888               d8P'    `Y8                                   
888           888   .oooo.   oooo  oooo   .oooo888   .ooooo.     Y88bo.      oooo    ooo ooo. .oo.    .ooooo.  
888           888  `P  )88b  `888  `888  d88' `888  d88' `88b     `"Y8888o.   `88.  .8'  `888P"Y88b  d88' `"Y8 
888           888   .oP"888   888   888  888   888  888ooo888         `"Y88b   `88..8'    888   888  888       
`88b    ooo   888  d8(  888   888   888  888   888  888    .o    oo     .d8P    `888'     888   888  888   .o8 
 `Y8bood8P'  o888o `Y888""8o  `V88V"V8P' `Y8bod88P" `Y8bod8P'    8""88888P'      .8'     o888o o888o `Y8bod8P' 
                                                                             .o..P'                            
                                                                             `Y8P'

ClaudeSync is a powerful tool designed to seamlessly synchronize your local files with Claude.ai projects.

Overview and Scope

ClaudeSync bridges the gap between your local development environment and Claude.ai's knowledge base. At a high level, the scope of ClaudeSync includes:

Real-time synchronization with Claude.ai projects
Command-line interface (CLI) for easy management
Multiple organization and project support
Automatic handling of file creation, modification, and deletion
Intelligent file filtering based on .gitignore rules
Configurable sync interval with cron job support
Seamless integration with your existing workflow
Optional two-way synchronization support
Configuration management through CLI
Chat and artifact synchronization and management

Important Note: ClaudeSync requires a Claude.ai Professional plan to function properly. Make sure you have an active Professional subscription before using this tool.

Important Disclaimers

Data Privacy: ClaudeSync does not share any personal data or project data with anyone other than Anthropic (through Claude.ai) and yourself. Your data remains private and secure.
Open Source Transparency: We are committed to transparency. Our entire codebase is open source, allowing you to review and verify our practices.
Affiliation: ClaudeSync is not affiliated with, endorsed by, or sponsored by Anthropic. It is an independent tool created by enthusiasts for enthusiasts of Claude.ai.
Use at Your Own Risk: While we strive for reliability, please use ClaudeSync at your own discretion and risk. Always maintain backups of your important data.

Quick Start

Install ClaudeSync:
```
pip install claudesync
```
Login to Claude.ai:
```
claudesync api login claude.ai
```
Select an organization:
```
claudesync organization select
```

Select or create a project:

claudesync project select
# or
claudesync project create

Start syncing:
```
claudesync sync
```

Advanced Usage

API Management

Login to Claude.ai: claudesync api login claude.ai
Logout: claudesync api logout
Set upload delay: claudesync api ratelimit --delay <seconds>

Organization Management

List organizations: claudesync organization ls
Select active organization: claudesync organization select

Project Management

List projects: claudesync project ls
Create a new project: claudesync project create
Archive a project: claudesync project archive
Select active project: claudesync project select

File Management

List remote files: claudesync ls
Sync files: claudesync sync

Chat Management

List chats: claudesync chat ls
Sync chats and artifacts: claudesync chat sync
Delete chats: claudesync chat rm
Delete all chats: claudesync chat rm -a

Configuration

View current status: claudesync status
Set configuration values: claudesync config set <key> <value>
Get configuration values: claudesync config get <key>
List all configuration values: claudesync config list

Synchronization Modes

One-Way Sync (Default)

By default, ClaudeSync operates in one-way sync mode, pushing changes from your local environment to Claude.ai. This ensures that your local files are the source of truth and prevents unexpected modifications to your local files.

Two-Way Sync (Experimental)

Two-way synchronization is available as an experimental feature. This mode allows changes made on the remote Claude.ai project to be reflected in your local files. However, please be aware of the following:

To enable two-way synchronization:
```
claudesync config set two_way_sync true
```
Caution: Claude.ai has a tendency to modify filenames, often appending descriptive text. For example, "README.md" might become "Updated README.md with config and two-way sync info.md". This behavior is currently beyond ClaudeSync's control.
Potential Data Loss: Due to the filename modification issue, there's a risk of unintended file duplication or data loss. Always maintain backups of your important files when using two-way sync.
Future Improvements: We're actively exploring ways to mitigate these issues, possibly through prompt engineering or updates to ClaudeSync. For now, this feature is provided as-is and should be used with understanding of its limitations.

Scheduled Sync

Set up automatic syncing at regular intervals:

claudesync schedule

Providers

ClaudeSync offers two providers for interacting with the Claude.ai API:

claude.ai (Default):
- Uses built-in Python libraries to make API requests.
- No additional dependencies required.
- Recommended for most users.
claude.ai-curl:
- Uses cURL to make API requests.
- Requires cURL to be installed on your system.
- Can be used as a workaround for certain issues, such as 403 Forbidden errors.
Note for Windows Users: To use the claude.ai-curl provider on Windows, you need to have cURL installed. This can be done by:
- Installing Git for Windows (which includes cURL)
- Installing Windows Subsystem for Linux (WSL)
Make sure cURL is accessible from your command line before using this provider.

Custom Ignore File

ClaudeSync supports a custom ignore file named .claudeignore for specifying patterns of files to exclude from syncing, using the same syntax as .gitignore.

Troubleshooting

403 Forbidden Error

If you encounter a 403 Forbidden error when using ClaudeSync, it might be due to an issue with the session key or API access. Here are some steps to resolve this:

Ensure you have an active Claude.ai Professional plan subscription.

Try logging out and logging in again:

claudesync api logout
claudesync api login claude.ai

If the issue persists, you can try using the claude.ai-curl provider as a workaround:
```
claudesync api logout
claudesync api login claude.ai-curl
```

If you continue to experience issues, please check your network connection and ensure that you have the necessary permissions to access Claude.ai.

Contributing

We welcome contributions! Please see our Contributing Guidelines for more information.

Communication Channels

Issues: For bug reports and feature requests, please use our GitHub Issues.
Discord: For general development discussions, visit our Discord server.

License

ClaudeSync is licensed under the MIT License. See the LICENSE file for details.

Related Projects

Claude.ai: The AI assistant that ClaudeSync integrates with.

Made with ❤️ by the ClaudeSync team

godlaugh / ClaudeSync