Claude Sync Sessions

A VSCode extension that syncs your Claude Code sessions — messages, sub-agent transcripts, todos, and file-history — between machines via a private Git repository (e.g. Forgejo) or a self-hosted HTTP server. It rewrites the absolute project paths embedded in sessions so a conversation started on one machine resumes correctly on another, even when your projects live under a different directory.

Install (from source)

npm install
npm run compile

Then press F5 in VSCode to launch an Extension Development Host, or run npm run package to produce a .vsix and install it via "Extensions: Install from VSIX…".

Configure

• Claude Sync: Configure Device — set a device name and your projects root (the parent directory that contains your projects on this machine).
• Claude Sync: Set Git Repository URL — point at a private Git/Forgejo repo (SSH or HTTPS). Authentication is handled by your system git.
• For a self-hosted server instead: Claude Sync: Set Server URL (the access token is stored in VSCode SecretStorage, never in plain settings). Set claudeSyncSessions.backend to server.

Use

The Claude Sync activity-bar icon opens two views:

• Local Sessions — your sessions grouped by project. The inline ↑ uploads one session; the title-bar Upload All uploads every local session. A project's inline button uploads just that project.
• Remote Bundles — sessions stored in your repo/server. The inline ↓ downloads one; the title-bar Download All downloads everything.

Bulk operations show progress and a summary (done / failed); a single failure never aborts the batch.

Automatic sync (hooks)

Claude Sync: Install Auto-Sync Hooks registers Claude Code SessionEnd (push) and SessionStart (pull) hooks in ~/.claude/settings.json. These run even when Claude Code is used from a terminal. The status bar shows Claude Sync: Hooks ON/OFF (click to toggle). Remove Auto-Sync Hooks cleanly removes only the entries this extension added.

How paths are handled

Claude Code sessions embed absolute project paths in many places. On upload, the project path and your home directory are replaced with the tokens ${PROJECT_ROOT} and ${HOME}. On download, those tokens are rewritten to this device's paths (computed from projectsRoot). Each bundle carries a SHA-256 checksum that is verified on download.

Conflicts & backups

Conflicts use last-writer-wins: when downloading, if your local copy of a session is newer than the incoming bundle it is kept; otherwise the local copy is backed up under ~/.claude-sync-sessions/backups/<timestamp>/ before being overwritten.

Settings

Setting	Default	Purpose
claudeSyncSessions.backend	git	git or server.
claudeSyncSessions.gitRepoUrl	""	Private Git/Forgejo repo URL.
claudeSyncSessions.serverUrl	""	Self-hosted server base URL.
claudeSyncSessions.deviceName	""	This device's identifier.
claudeSyncSessions.projectsRoot	""	Parent directory of your projects on this device.
claudeSyncSessions.autoRefreshOnFocus	true	Refresh local sessions when the window regains focus.

The server token is stored in VSCode SecretStorage, not in settings.

Data locations

• Local Git mirror: ~/.claude-sync-sessions/repo
• Conflict backups: ~/.claude-sync-sessions/backups/
• Hooks launcher: ~/.claude-sync-sessions/bin/hook.cjs
• Shared config (read by hooks): ~/.claude-sync-sessions/config.json
• Hook log: ~/.claude-sync-sessions/hook.log

Limitations

• The self-hosted server itself is out of scope here — only the client is included.
• Windows project-directory-name encoding has not yet been verified end-to-end.