ctxsync pushes a local directory into a Claude.ai project, one way

A local directory mirrored into a Claude.ai project

ctxsync is a Python tool that automates the synchronization of local files with Claude.ai projects, and it was formerly known as ClaudeSync. The bridge it builds is a one-way pipe from your machine into a project in the Claude.ai web application, which is useful because projects are the place where reference files live for a conversation, and keeping them in step by hand is tedious. The feature list is short and describes the shape of the tool. File sync with Claude.ai projects. Cross-platform compatibility with Windows, macOS and Linux. Plenty of configuration options, linked to a quick reference page in the wiki. It is designed to be easy to integrate into pipelines, and it claims to ensure data privacy and security. The repository is a src layout Python package with a CLI entry point at ctxsync.cli.main:cli, a pytest configuration, a SECURITY.md, a CODEOWNERS file and a claudesync-shim directory that presumably keeps the old command name working. The topic list is narrow, claude-ai, llm, productivity-tool and python, which is an accurate description of a focused developer utility rather than a platform.

The push deletes what is missing locally

The single most important sentence in the documentation is the warning attached to the push command, and it should be read before anything else. This is a one-way sync, and files not present locally will be removed from the Claude.ai project unless pruning is disabled, with a link to the pruning-remote section of the configuration quick reference. That default is aggressive. A push from the wrong working directory, or from a directory whose contents were moved, deletes what was uploaded before. The reasoning behind the design is reasonable, since a sync that leaves stale files behind stops being a mirror, and the tool offers a way to turn the behaviour off. But the failure mode is not symmetric, because a wrong push loses remote state that the local side never had. The practical rules follow from that. Sync from a dedicated directory that mirrors the project layout, confirm what pruning is set to before the first push, and keep the local side as the copy you trust, since a re-push rebuilds the remote from it. The dependencies give a hint about the mechanism, with pathspec for pattern matching, Brotli for compression and cryptography in the list, but the README does not describe the transport or the API calls in detail.

Credentials in an SSH key, and a plan that has to qualify

Two prerequisites decide whether you can use the tool at all. The first is the Claude.ai plan. The documentation tabulates which are supported, and Pro and Team are supported while Free is not. The second is an SSH key, which the README asks you to have for secure credential storage, pointing at GitHub's guide for generating and adding an SSH key. Storing a credential in an SSH key rather than in a config file is a sensible default, and it also means the tool inherits a well understood mechanism for key handling rather than inventing one. The install itself is a single command, and the first run is three more:

pip install ctxsync

ctxsync auth login

ctxsync project create

ctxsync push

The auth login step is what binds the local configuration to your account, project create sets up the remote side, and push performs the synchronisation. Python 3.10 or newer and pip are the only software requirements, and the packages are released for all three major operating systems.

From ClaudeSync to ctxsync without losing your settings

The rename was handled carefully, which is worth noting because renaming a published package is usually where projects break. The documentation says the claudesync PyPI package is deprecated and you should install ctxsync instead, and that your existing configuration is picked up automatically, with ~/.claudesync migrated on first run and project-local .claudesync directories kept working. So an upgrade is a matter of changing what you install, not rebuilding your setup. The tree supports that story, since the claudesync-shim directory is a deliberate compatibility layer rather than an accident of history. The version numbering tells a similar story, with the manifest at 0.8.0 while the most recent tagged releases are v0.7.6 on 2026-03-08, v0.7.5 on 2025-12-01 and v0.7.4 on 2025-11-16, and the last push on 2026-06-11. The package metadata names Jahziah Wagner as the author, and the project is MIT licensed with the licence file referenced from the manifest.

Scheduling and streaming show up in the dependency list

The dependency set is a good way to read the intended use, even though the README does not spell out the features. click and click_completion provide the command line and shell completions. pathspec handles path pattern matching, which is how a sync decides what is in scope. python_crontab and crontab are both present, along with a cron-related keyword in the package metadata, which points to a scheduling path for unattended syncing. sseclient_py is a client for server-sent events, so the tool appears to consume a streaming endpoint rather than polling, and that is consistent with a push that reports progress on a long operation. tqdm is the progress bar, Brotli is the compression, and cryptography is present for the credential handling. The keywords list is worth reading as a statement of intent, with sync, files, Claude.ai, automation, cloud sync, cli tool, productivity, development tools, file synchronization, continuous integration, devops and version control. The connection to cron and to continuous integration is the interesting part, since it means the tool is meant to run unattended, which raises the stakes on the pruning default described earlier.

The disclaimer is the honest summary of this project

ctxsync ships a disclaimer that is unusual for a productivity tool, and it deserves to be quoted rather than paraphrased. The project is an independent, open source project not affiliated with Anthropic or Claude.ai, and by using it you agree to use it at your own risk, to acknowledge a potential violation of Anthropic's terms of service, to assume responsibility for any consequences, and to understand that Anthropic does not support the tool. The documentation asks you to review Anthropic's consumer terms before using it. That is an unusually direct statement, and it tells you the actual situation. The tool drives a service surface that the vendor does not document as a public API and does not support, which means it can break without notice, and it means your account is exposed to whatever enforcement Anthropic chooses to apply. There is also a documentation level below the top of the README, with detailed guides and FAQs in the project wiki, a contribution file, a Discord channel and a sponsorship link, so the project is a real community effort rather than a script. For a reader deciding whether to use it, the sensible summary is that the code is small, permissively licensed and MIT, the workflow is four commands, and the risk is not technical but contractual, and it is entirely on the person running it.

Editorial conclusion

Adopt ctxsync if you already keep context files in a local directory and want that same set to appear in a Claude.ai project without hand-uploading them, and if you are prepared to treat the push as the source of truth. Do not adopt it for two-way editing, because the sync is one-way and prunes remote files, and do not adopt it if your account or your organisation forbids unsupported API clients, since the project's own disclaimer asks you to acknowledge a possible breach of Anthropic's terms. Before you run the first push, disable pruning or work on a copy, confirm you are on a Pro or Team plan, and set up the SSH key that holds the credentials.

Frequently asked questions

Official sources

1. Issues
2. jahwag/ctxsync on GitHub
3. License: MIT
4. README
5. Releases