repository·master·Indexed 20 days ago
https://github.com/jahwag/ctxsyncctxsync (version 0.8.0) is a tool designed to synchronize local development files with Claude.ai projects. It provides a CLI for managing authentication, project files, and chat conversations, including features for one-way synchronization via `push`, file category management, and generating text embeddings from project files. It is the successor to the deprecated claudesync package and requires Python 3.10+, an SSH key for credential storage, and a Claude.ai Pro or Team plan.
Install the ctxsync package using pip. Note that ctxsync is the successor to the deprecated claudesync package. If you previously used claudesync, your existing configuration in ~/.claudesync will be automatically migrated to ctxsync on the first run, and project-local .claudesync directories will continue to function.
pip install ctxsyncBefore using ctxsync, ensure you meet the following requirements:
Follow these steps to set up and start synchronizing your local files with Claude.ai projects:
pip install ctxsyncctxsync auth login.ctxsync project create.ctxsync push to upload local files to the Claude.ai project.Warning: ctxsync push performs a one-way sync. By default, files present in the Claude.ai project that are NOT present in your local directory will be removed from the remote project. You can disable this behavior by configuring the pruning-remote option.
pip install ctxsync
ctxsync auth login
ctxsync project create
ctxsync pushThe claudesync package is deprecated and has been renamed to ctxsync. To migrate to the current version, uninstall the old package and install ctxsync.
Existing configurations are automatically migrated:
~/.claudesync is migrated on the first run of ctxsync..claudesync directories remain compatible and will continue to work.pip uninstall claudesync
pip install ctxsyncctxsync includes automatic migration logic for users of the previous tool, ClaudeSync:
~/.claudesync is automatically copied to ~/.ctxsync to preserve settings and session keys..claudesync directories.ctxsync uses a hierarchical configuration system consisting of two layers:
~/.ctxsync/config.json. This contains settings applicable to all projects, such as file categories and SSH key paths..ctxsync/config.local.json file found by searching upwards from the current working directory. This is used for project-specific settings like the active_provider or specific submodule paths.When retrieving a setting via get(), ctxsync checks the local configuration first and falls back to the global configuration if the key is not found locally.
Initialize a new local project configuration. This creates a .ctxsync directory in your local path and saves the configuration.
If you use the --new flag, ctxsync will also create a corresponding remote project on Claude.ai. If you are linking to an existing remote project, do not use --new; instead, use ctxsync organization set and ctxsync project set to link your local directory to the remote project.
# Initialize a local-only project
ctxsync project init --name "My Project" --local-path "/path/to/dir"
# Initialize and create a new remote project on Claude.ai
ctxsync project init --name "My New Remote Project" --newThe create command is a convenient alias for ctxsync project init --new. It automates the process of creating both the local configuration and a new remote project on Claude.ai.
ctxsync project create --name "My New Project"The InMemoryConfigManager is a configuration manager that stores settings entirely in memory using Python dictionaries. It does not persist data between program runs. This is useful for temporary runtime configurations or when you want to avoid writing sensitive session data to disk.
Key behaviors:
set method.get, the manager first checks the local configuration; if the key is not found, it falls back to the global configuration.from ctxsync.configmanager import InMemoryConfigManager
config = InMemoryConfigManager()
# Set a global setting
config.set("api_version", "v1")
# Set a local setting
config.set("active_provider", "claude", local=True)
# Retrieve settings (checks local first, then global)
version = config.get("api_version")
provider = config.get("active_provider")Use the create command to start a new session. If you are inside a git repository, ctxsync will attempt to automatically link the local repository to the session. You can specify a title, an environment ID, a specific model, or a branch name. After creation, the CLI will automatically begin streaming live session events (like Claude's messages and status updates) to your terminal.
ctxsync session create "My Session Title" --environment-id "env_123" --model "claude-sonnet-4-5-20250929" --branch "feature-branch"If you need to implement a custom way to manage settings (e.g., loading from a specific database or a custom file format), you should subclass BaseConfigManager.
BaseConfigManager provides a dual-layer configuration model:
global_config: Settings that apply universally across all environments.local_config: Settings specific to the current environment or project.To create a functional implementation, you must implement the following abstract methods:
_load_global_config(): Logic to load global settings._load_local_config(): Logic to load local settings._save_global_config(): Logic to persist global settings._save_local_config(): Logic to persist local settings.set(key, value, local=False): Logic to update a setting. Use local=True to target the local context.get(key, default=None): Logic to retrieve a setting. Implementations should check the local context first, then fall back to the global context._find_local_config_dir(): Logic to locate the directory for local configuration files.Use session branch ls to list repositories available for Claude Code sessions. You can filter the list using the --search flag to find a specific repository by name.
# Search for a specific repository
ctxsync session branch ls --search "my-repo-name"
# Output list in JSON format
ctxsync session branch ls --json