Sync

Documentation that can't quietly rot.

Your coding agent writes the docs as it works — and git flags every entry stale the moment the code moves past it. No audits. No rot. No silent lies.

⬇ Download

macOS · Windows · Linux (AppImage) · Linux (.deb)

_{always the latest release · all releases · macOS build is Apple Silicon — Intel & other targets build from source}

Features · How it works · Connect an agent · Download

---

Features

• 🤖 Your agent stops repeating itself. It reads the relevant spec, decisions, and constraints before writing a line — so it stops re-introducing the bug you killed last month or the design you already rejected.
• 🚩 Docs that raise their hand when they rot. The moment a commit moves past a doc, git marks it stale — pointing at the exact commit and files. Staleness becomes a worklist, not a guess.
• ✍️ The work documents itself. Specs, decisions, constraints, open questions — captured by the agent as it codes, reviewed by you inline like comments on a PR.
• 📦 Everything in your repo. Plain files under .sync/, versioned by git. No SaaS, no account, no upload — nothing leaves your machine.
• 🔎 Search that runs on your laptop. Full-text plus optional on-device semantic search (nomic-embed via llama.cpp), across every project. Offline, private.
• 🧭 A roadmap that answers "what's next?" Goals → milestones → specs, ordered by priority and by which specs your recent commits actually touched.
• 🧩 Works where you already work. Claude Code, Cursor, Zed, Codex, OpenCode — one binary, one MCP line.

Why this exists

Documentation rots. AI coding agents make it worse: they pattern-match against whatever stale text they find, hallucinate the gaps, and re-introduce decisions you overturned six months ago.

The fix isn't more docs. It's a knowledge layer that has structure an agent can reason over, lives in your repo and in git, gets written by the agent as it works, and flags itself stale when the code around it moves. Sync is that layer.

How it works

Sync uses git to know when a doc has fallen out of date — no manual audits, no hoping someone remembers.

Each spec, doc, and knowledge entry records the code paths it describes (scope_paths) and the commit it was last verified against. A managed git hook runs a path-driven invalidator over every new commit; when a commit touches those paths — or a linked entry changes underneath it — Sync marks the entry stale, stamping exactly which commit and which files moved. Nothing is rewritten or guessed: the doc simply stops claiming to be current.

From there, staleness is a worklist:

• git sync revalidate re-stamps an entry against HEAD once you confirm it still holds.
• git sync precheck is a pre-push gate — it exits non-zero while stale entries are pending, so out-of-date docs can't quietly ship.
• The desktop app and git_sync_status surface the stale set and a per-project stale ratio, so you always know how current the knowledge base really is.

That trustworthiness is the point — an agent can act on docs it knows are fresh.

Run your agent inside Sync

This is the part that clicks the moment you see it. Open a repo in the desktop app, launch your agent — Claude Code, Codex, or OpenCode — in the built-in terminal, and it already knows what you're looking at: click a spec, type "implement this," and the agent resolves it to that spec. No copy-paste, no re-explaining.

A session looks like:

1. Agent reads the spec before touching code.
2. Agent files an open question when something's ambiguous — instead of guessing.
3. You answer it right there; the answer becomes a canonical, attributed part of the spec.
4. Agent records decisions, constraints, observations as it works; you review them inline.
5. Code moves; Sync flags the affected entries stale. The next session starts from a known-fresh baseline.

Connect any agent

The Sync binary is the MCP server — git-sync mcp over stdio, no daemon. The Welcome wizard wires up Claude Code, Cursor, Zed, OpenCode, and Codex for you. For anything else, point your client at it:

claude mcp add git-sync -- git-sync mcp

Any MCP client, by config

{
  "mcpServers": {
    "git-sync": {
      "command": "git-sync",
      "args": ["mcp"]
    }
  }
}

Omit --root and the server resolves the repo from the working directory; add "--root", "/path/to/repo" to pin one project (or a workspace anchor for cross-project access). Use the binary's full path if it isn't on your PATH. The agent then has all 40-plus tools against your .sync/ knowledge base.

The knowledge model

Stored as YAML under .sync/, addressable by stable IDs, linkable to each other:

Kind	What it is
spec	Canonical description of a feature or system — the agent's primary read target.
decision	"We chose X over Y, because …" — rationale plus links to the constraints that forced it.
constraint	A hard or soft rule the codebase must respect.
observation	Something true about the system right now (perf number, gotcha, current behaviour).
question	An open question, blocking or not, with optional answer. Authored by humans or agents.
artifact	A pinned external reference — Figma, gist, URL, file.
doc	Free-form Markdown, with per-block discussion threads.
goal / milestone	Outcome-level tracking; the Roadmap rolls specs up under them.

The Roadmap turns this into "what should I work on next?" — ordered by horizon, priority, and which specs recent commits actually touched. Agents reach it through git_sync_plan.

Download & install

Grab a prebuilt build — no toolchain required:

Platform	File
macOS (Apple Silicon)	Download .dmg
Windows	Download .exe installer
Linux (AppImage)	Download .AppImage
Linux (Debian/Ubuntu)	Download .deb

On macOS, drag Sync.app to /Applications and launch it. The Welcome wizard registers the MCP server with your editors and promotes the git-sync CLI to your PATH. Change any of it later from Settings → Integrations (⌘,).

Build from source (Intel Macs, other targets, or hacking on Sync)

Requires Rust 1.91 (pinned via rust-toolchain.toml) and Node 20.19+ for the desktop bundle.

# CLI + MCP server only (one binary)
cargo build --release -p sync-app
./target/release/git-sync --version

# Desktop app (debug)
cargo install tauri-cli --locked
cargo tauri dev --config crates/sync-app/tauri.conf.json

# Desktop app (release bundle)
cargo tauri build --config crates/sync-app/tauri.conf.json

Privacy

Local-first by construction.

• Knowledge lives in .sync/ inside your repo. It never leaves your machine unless you git push it.
• MCP server uses stdio. No network sockets are opened.
• Embedding model (opt-in) downloads once over HTTPS into a per-user cache; point it at any local GGUF file instead.
• No telemetry. Ever.

Status

Alpha. The data model is stabilising; expect breaking changes to .sync/ formats before 1.0 (with a migration each time). macOS is the primary desktop target today; Linux and Windows compile but are less battle-tested. CLI and MCP run anywhere Rust 1.91 builds.

Hit a rough edge? Open an issue — the project lives or dies on real friction reports.

Contributing

Issues and pull requests are welcome — bug reports, friction reports, and docs fixes especially.

• Build and test with cargo build / cargo test; the desktop frontend lives under web/ (npm install, npm test).
• CI runs rustfmt, clippy, and the frontend lint/test suite — run them locally before opening a PR.
• See SECURITY.md for responsible disclosure of security issues.

License

FSL-1.1-MIT — Functional Source License, reverting to MIT two years after each release. Free for all non-competing use; the only thing prohibited is repackaging Sync as a competing product during the FSL period.

---

_{Security disclosures: see SECURITY.md.}