https://github.com/qiaeru/claude-code-sync
A small tool that syncs your Claude Code configuration across machines, offline and encrypted.
https://github.com/qiaeru/claude-code-sync
backup claude claude-code encryption offline sync zip
Last synced: 9 days ago
JSON representation
A small tool that syncs your Claude Code configuration across machines, offline and encrypted.
- Host: GitHub
- URL: https://github.com/qiaeru/claude-code-sync
- Owner: qiaeru
- License: mit
- Created: 2026-05-30T20:34:24.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-07-04T19:50:20.000Z (12 days ago)
- Last Synced: 2026-07-04T21:13:19.214Z (12 days ago)
- Topics: backup, claude, claude-code, encryption, offline, sync, zip
- Language: Python
- Homepage:
- Size: 392 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: docs/security.md
Awesome Lists containing this project
README
# Claude Code Sync
[](./LICENSE)
[](https://github.com/qiaeru/claude-code-sync/releases)
[](https://www.python.org/)
[](https://github.com/qiaeru/claude-code-sync/stargazers)
A small tool that syncs your [Claude Code](https://claude.com/claude-code) configuration across machines, offline and encrypted.
Instead of relying on an online service, it bundles your config into a single password-protected ZIP (AES-256) that you move however you like (USB stick, your own cloud, scp…) and import on another machine. A small local web UI drives both export and import, so you never have to remember command-line flags; a headless CLI is available for automation. Inspired by [jean-claude](https://github.com/MikeVeerman/jean-claude), then rebuilt for an offline, encrypted export/import workflow.
> **Offline by design.** No account, no telemetry, no external network call at runtime. The web UI binds to `127.0.0.1` only, and your password never leaves memory.
## Highlights
### What it does
- **Two scopes.** Per-project config (every `CLAUDE.md` at any depth and the project `.claude/` directory) and the global `~/.claude/` (`settings.json`, `keybindings.json`, `CLAUDE.md`, and the `skills/`, `agents/`, `commands/`, `hooks/`, `plugins/` directories).
- **Encrypted, portable archives.** Standard WinZip-AES (AES-256) ZIPs you can also open with 7-Zip or any AES-capable tool using the same password.
- **Safe imports.** Existing files are backed up to `~/.claude-code-sync-backups//` before being overwritten, every restored file is verified against a SHA-256 in the manifest, and a dry-run previews the changes first. A **Backups** tab lists those backups and prunes the old ones.
- **Selective sync.** Tick or untick individual files in the preview to export or restore only a subset.
- **Web UI and CLI.** A claude.ai-flavored local UI with light/dark themes, drag-and-drop, and native file pickers, plus `export` / `import` subcommands for scripts and cron.
### Under the hood
- **Your secrets stay put.** The global scope uses a strict allow list, so files like `~/.claude/.credentials.json`, your chat history, and `settings.local.json` are never archived.
- **Hardened.** Path-traversal rejection and size-bounded extraction (decompression-bomb guard) on import, archive integrity checks, a local-only server that rejects cross-origin / DNS-rebinding requests.
- **Self-contained.** One runtime dependency (`pyzipper`); the web server is pure standard library; fonts and icons are bundled. Runs unmodified on an air-gapped host.
- **Quality-gated.** Type-hinted, `ruff`- and `mypy`-clean, tested on Linux and Windows via GitHub Actions.
## Requirements
- Python 3.11+
- One runtime dependency: [`pyzipper`](https://pypi.org/project/pyzipper/) (AES ZIP)
## Quick start
Place the `claude-code-sync` folder directly inside the directory that holds your projects (the folder whose sub-folders are your repos), then:
```bash
git clone https://github.com/qiaeru/claude-code-sync.git
cd claude-code-sync
pip install -r requirements.txt # or: pip install .
python -m claude_code_sync # launches the web UI in your browser
# or double-click run.bat (Windows) / run ./run.sh (Linux/macOS)
```
In the **Export** tab, check the root, choose a scope, set a password, preview, then create the archive. Move the resulting `claude-code-sync--.zip` to the other machine and restore it from the **Import** tab (dry-run first).
For automation, the same logic is available headless (here `~/GitHub` is an example; use the folder that contains your projects):
```bash
claude-code-sync export --root ~/GitHub --scope all --out-dir .
claude-code-sync import bundle.zip --root ~/GitHub --dry-run
```
## Documentation
- [Usage guide](./docs/usage.md): scopes, passwords, backups, troubleshooting.
- [CLI reference](./docs/cli.md): headless `export` / `import`.
- [Configuration](./docs/configuration.md): the optional `.claude-code-sync.toml`.
- [What is collected](./docs/what-is-collected.md): exact include/exclude rules.
- [Architecture](./docs/architecture.md): local server, JSON API, core modules.
- [Security](./docs/security.md): encryption, hardening, threat model.
- [Development](./docs/development.md): setup, tests, project layout.
- [Building a binary](./docs/build.md): standalone executable via PyInstaller.
- [Contributing](./CONTRIBUTING.md)
- [Changelog](./CHANGELOG.md)
## Companion scripts
The [`scripts/`](./scripts/) folder holds self-contained helpers that ship inside this checkout and run in place, targeting the folder that holds your project repos. The sync tool keeps your Claude Code config in step across machines; these keep the surrounding repos and your backups tidy on both sides. Each has a Linux/macOS `.sh` and a Windows `.bat`.
- [`update-repos`](./scripts/update-repos/): fast-forward every Git repo in one run.
- [`status-repos`](./scripts/status-repos/): read-only status of every repo (branch, changes, ahead/behind).
- [`clean-backups`](./scripts/clean-backups/): prune the timestamped import backups the tool leaves in your home folder.
- [`backup-export`](./scripts/backup-export/): unattended encrypted export with retention, for cron or Task Scheduler.
## Credits
Third-party assets and libraries and their licenses are listed in [CREDITS.md](./CREDITS.md).
## License
Released under the MIT License. See [LICENSE](./LICENSE) for the full text.