Work Capsule

Keep your work in sync — one click pulls, (optionally) commits, and pushes every Git folder you choose.

English · 简体中文

One-Click Sync is the ready-to-use piece of Work Capsule today: a tiny, dependency-free Windows app — and a scriptable CLI — that keeps your Git folders backed up and in sync in a single click. It is safe by default (it never rewrites history or discards your work) and does exactly what you tell it to, no more.

Contents

• Features
• Download
• Quick start
• One-click backup — auto-commit
• Reading each result
• Configuration & logs
• Building from source
• Project layout
• How it works
• Roadmap
• Contributing
• License

Features

• One click, every repo — pull and push every configured folder ↔ remote binding at once.
• Optional one-click backup — flip on auto-commit per binding and a sync also commits every change in that folder first, so one click truly backs the folder up to GitHub.
• Two ways to run — a lightweight desktop GUI, or a scriptable CLI (--json output for automation).
• Safe by default — fast-forward-only pulls; it never merges, rebases, resets, stashes, force-pushes, or resolves conflicts. Anything ambiguous stops and reports; your working tree is left exactly as it was.
• Live status, quietly — a silent double-click sync shows only a small liquid-glass status capsule at the bottom of the screen (above), then gets out of your way.
• Editable rules — bind a local folder to a remote (two boxes: the folder, the URL); enable, disable, remove, or toggle auto-commit on any binding.
• Zero runtime setup — a single self-contained executable. The only requirement is Git on your PATH.
• Reusable engine — a pure-Rust core (crates/sync) with no dependency on the rest of the project; any Rust program can drive it.
• Every run is logged — appended to a rotating log file you can audit.

Download

1. Grab work-capsule-sync-gui.exe (GUI) and/or work-capsule.exe (CLI) from the Releases page — or build from source.
2. The executables are self-contained: no runtime, no installer. They only need Git on your PATH.
3. (Optional) Make a desktop shortcut to the GUI so a double-click runs a sync.

Quick start

Desktop app

1. Double-click work-capsule-sync-gui.exe — a dark, borderless window opens.
2. Under Add a sync, pick a local folder, paste its remote URL, and click Add.
3. Click ⟲ Sync all whenever you want to pull + push everything.

Command line

work-capsule sync                    # sync every configured repo
work-capsule sync add D:\notes --remote https://github.com/you/notes.git
work-capsule sync list               # show configured bindings
work-capsule sync remove notes
work-capsule sync --json             # machine-readable output (exit 0 = all clean)

One-click backup — auto-commit

By default Work Capsule pulls and pushes but does not create commits — it only moves commits that already exist. That is the safe choice for code, but for notes and writing you often just want "put my folder on GitHub" in one click. That is what auto-commit does.

Turn it on per binding (Edit a sync → tick Auto-commit → Save). Then one sync will:

1. commit every change in that folder as a single commit, then
2. pull (fast-forward), then push.

It stays off by default. Great for notes/writing repos; leave it off for code repos where you want to shape the history yourself. Diverged branches still stop for you either way — nothing is ever merged or rewritten on your behalf.

First-time sign-in (once per machine). Pushing needs a saved credential. On locked-down machines the interactive credential manager can hang; the fix is a Personal Access Token in Git's built-in store helper. Run scripts/setup-github-login.ps1, paste a fine-grained token (Contents: read & write), and you're set. The token never leaves your machine.

Reading each result

Tag	Meaning
[ok]	already in sync — nothing to do
[pull]	pulled new commits from the remote
[push]	pushed your local commits (auto-commit folds uncommitted changes in first)
[skip]	skipped (folder missing / not a Git repo / rule disabled)
[warn]	needs you: branches diverged, uncommitted changes in the way, detached HEAD, or the remote URL doesn't match
[auth]	Git sign-in failed (expired or missing credentials)
[offline]	remote unreachable — nothing changed locally
[fail]	other error; details are in the message

Without auto-commit, uncommitted changes never block a sync — they are left in place and only mentioned in the report. Diverged branches (both machines committed without syncing) are always left for you to resolve; the tool never merges on your behalf.

Configuration & logs

• Config — %APPDATA%\work-capsule\config\sync.json (human-editable JSON)
• Log — sync.log in the same folder; appended each run, rotated to sync.log.1 past 1 MiB
• Portable mode — set WORK_CAPSULE_CONFIG_DIR to relocate both to any directory

Building from source

Requires the Rust toolchain (Rust 2024 edition, 1.88+). The pinned target is x86_64-pc-windows-msvc, so linking needs the MSVC toolchain — install Visual Studio Build Tools with the Desktop development with C++ workload. rustup reads the channel, components, and target from rust-toolchain.toml automatically.

cargo build --release -p work-capsule-cli   # CLI  -> target/release/work-capsule.exe
cargo build --release -p work-capsule-gui   # GUI  -> target/release/work-capsule-sync-gui.exe
cargo test  --workspace

GUI icon: a plain cargo build links the exe but does not embed the app icon. To get the Explorer/taskbar/shortcut icon, build the GUI with scripts\build-gui.ps1 (it embeds the icon after linking — no resource compiler required). See scripts/README.md.

Project layout

A Cargo workspace. The shipping One-Click Sync tool is three crates; the rest is the in-progress "capsule" core (see Roadmap).

crates/
  sync/       one-click sync engine — pure Rust, reusable, no other in-repo deps
  cli/        work-capsule           — scriptable command line over the engine
  gui/        work-capsule-sync-gui  — egui desktop app (glow backend) + status capsule
  core/       capsule builder, deterministic review, session state   (in progress)
  git/        git snapshot & project watcher                          (in progress)
  protocol/   wire types shared across the future daemon/SDK          (in progress)
  storage/    SQLite-backed capsule store                             (in progress)
scripts/      build + icon + one-time GitHub login helpers (Windows/PowerShell)

The engine lives in crates/sync (work-capsule-sync) and depends on no other crate in this repo, so any Rust program can drive it directly:

let report = SyncEngine::new().run(&config).await; // never panics, never rewrites history

Non-Rust callers can use work-capsule sync --json and read the structured result (exit code 0 means everything is clean).

How it works

Each binding is checked in a fixed, conservative order: confirm it is a Git repo on a branch with a matching origin; fetch to learn the exact gap to the remote; then act only on that gap — fast-forward-pull when behind, push when ahead, and stop when diverged. Auto-commit, when enabled, runs one add -A + commit before the fetch. The engine never runs reset, clean, stash, merge, rebase, or anything --force; those subcommands are structurally absent from the code.

Roadmap

Beyond sync, Work Capsule aims to package a bounded work session — hook events, Git snapshots, decisions, and next steps — into a verifiable, portable capsule (not a copy of your whole project). That core (crates/core, crates/git, crates/protocol, crates/storage) is under construction; the same sync engine will later be callable from a Tauri desktop app, a CLI, or an Electron host.

Contributing

Issues and pull requests are welcome. Before opening a PR:

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test  --workspace

CI runs the same three checks on Windows. Keep the engine's safety guarantees intact — no new destructive Git subcommands, and anything ambiguous should stop and report rather than guess.

License

MIT © the Work Capsule authors