Sync Across Machines

Claustre can sync project and task state across machines via a git repo at ~/.claustre/sync/. Only projects, tasks, and subtasks are synced — sessions and runtime state stay local to each machine.

What Gets Synced

Projects are matched by name across machines. The same project can live at different paths on each laptop — claustre handles the mapping automatically.

Enable Sync on an Existing Installation

If you already have claustre running with projects and tasks:

# 1. Create a private repo on GitHub (or any git host)
#    e.g. https://github.com/you/claustre-sync

# 2. Initialize the sync repo by cloning it
claustre sync init git@github.com:you/claustre-sync.git

# 3. Push your current state
claustre sync push

This exports all your projects and tasks as JSON files to ~/.claustre/sync/, commits them, and pushes to the remote. Your existing claustre setup is not modified — sync only reads from the database.

Enable Sync on a Fresh Installation

If you're setting up claustre for the first time and don't have a sync repo yet:

# 1. Install and configure claustre
claustre configure

# 2. Initialize a local sync repo (no remote yet)
claustre sync init

# 3. Add a remote when you're ready
git -C ~/.claustre/sync remote add origin git@github.com:you/claustre-sync.git

# 4. Add projects, create tasks, then push
claustre sync push

You can also skip steps 2–3 and use claustre sync init <url> directly if you already have the remote repo created.

Sync a Second Laptop

If you already have sync set up on one machine and want to bring a second laptop up to speed:

# 1. Install claustre on the new machine
claustre configure

# 2. Clone your existing sync repo
claustre sync init git@github.com:you/claustre-sync.git

# 3. Register the same projects locally (paths will differ per machine)
claustre add-project myproject ~/code/myproject
claustre add-project another ~/work/another

# 4. Pull the synced state
claustre sync pull

The pull imports tasks into the matching local projects. Any synced project that isn't registered locally is skipped with a message telling you to add-project first.

Day-to-Day Workflow

# On laptop A: finish working, push state
claustre sync push

# On laptop B: pull latest before starting
claustre sync pull

# ... work on tasks ...

# On laptop B: push when done
claustre sync push

push is idempotent — if nothing changed, it prints “No changes to sync” and does nothing. pull upserts tasks by UUID, so it safely handles both new and updated tasks without duplicating anything.

How It Works

State is exported as one JSON file per project under ~/.claustre/sync/projects/. Each file contains the project metadata and all its tasks (with subtasks inline). Task UUIDs are preserved across machines so upserts work correctly.

The sync directory is a regular git repo. You can inspect, diff, or manually edit the JSON files if needed. Claustre also copies config.toml into the sync directory for reference, but does not auto-import it on pull.

CLI Reference

claustre sync init [url]    # Initialize sync repo (clone if URL given, or local-only)
claustre sync push          # Export state, commit, push
claustre sync pull          # Pull from remote, import into local DB
claustre sync cd            # Change to sync directory (requires shell-init)