File claims and presence with no server · Synchrobuilder

Each working tree publishes exactly one ref on the team's remote: refs/synchrobuilder/v1/<handle>/<device>/<seat>. The handle is a short name matched from your git email through the committed team file (ADR-002); the device id is a random 8-hex value made once per machine and stored locally, never the hostname; the seat identifies one working tree, so two agents in two worktrees of the same clone are two participants rather than one. Refs published before seats existed have two segments and are still read. The tip of that ref is always a parentless snapshot commit whose tree holds only that writer's files: presence, claims, board entries, contract alerts, messages, handoffs and a small manifest that readers check against the ref name.

There are no merges, ever. The writer builds each snapshot with git plumbing (hash-object, mktree, commit-tree) and pushes with --force-with-lease, never bare --force. It never reads anyone else's state before writing, so nothing a teammate pushes can stop you publishing. Every commit message starts with [skip ci]. A custom ref namespace stays out of branch lists, and the design expects it to sit outside branch rulesets. GitHub's reference API documentation accepts any name that starts with refs/ and has two slashes. GitHub accepts the namespace: a hosted check on 2026-09-18 passed 11 of 11, including the ref staying out of git branch -a and triggering no workflow run. GitLab, Bitbucket and Azure DevOps have not been tested, and a repository-wide ruleset refusing the state ref has not been tried.

The fallback ladder: if a host rejects the custom namespace, the plugin falls back to branches under refs/heads/synchrobuilder/v1/ in fast-forward append mode, with [skip ci] and -o ci.skip on every push. If that is rejected too, it goes read-only (fetch only) or local-only and records the server's reason so the digest can say why publishing is blocked. The branch-mode fallback was exercised against GitHub; a provider actually rejecting the namespace has not been observed, because no provider did.

All git work happens in a hidden bare repository under ~/.synchrobuilder/remotes/<sha256 of the normalized remote URL>/state.git, run by a detached Node worker. Your own .git is never written to, and your branches and working tree are never touched. The worker fetches every 45 seconds plus up to 15 seconds of jitter, and pushes only when your state changed or 60 seconds passed. Important events (a claim, a release, a message, a board change, a handoff, a closed session) trigger a sync tick within about a second. Credentials come from your global git configuration only; git is spawned as an argument list with no shell and with per-call timeouts.

Hooks never run git and never open a socket. They find the checkout by reading .git/config and the gitdir and commondir files, then read snapshot.json from the plugin's own state directory under ~/.synchrobuilder. Every hook runs inside one try/catch; on any error it writes one line to a local log, prints nothing and exits 0. It never exits 2, so it can never block you.

What the hooks tell Claude depends on how fresh the snapshot is. Under 5 minutes old: full policy. Between 5 and 15 minutes: an ask collision setting degrades to warn. Over 15 minutes: warn only, with an "as of HH:MMZ" stamp. Over 24 hours: only the session digest mentions that sync is stale. Stale data never blocks and never asks.

Verified: two developers over a real bare remote, in tests/e2e/multiplayer.test.mjs, on ubuntu, macOS and Windows in CI. It drives the real CLI, hooks and worker through presence, a collision warning, a message, a handoff and an offline period, then asserts that a claim made while the remote was away arrives once it is back and that neither repository was written to: no worktree change, no local branch, nothing under .git. Against real GitHub, a hosted check on 2026-09-18 passed 11 of 11: the push is accepted, --force-with-lease replaces the writer's own ref, the ref stays out of git branch -a while showing in ls-remote, a second clone round-trips the JSON, main is untouched, the branch-mode fallback publishes, and no Actions run is triggered. Not verified: GitLab, Bitbucket and Azure DevOps; branch protection rules refusing the state ref; recovery from a deliberately poisoned ref or a mirror push that deletes the namespace, neither of which has a test yet.

Contract change alerts carry repo-relative paths and exported symbol names only. This is a deliberate difference from claude-code-relay, which sends the code-stripped prose of Claude's replies and contract-file diff hunks; Synchrobuilder sends neither. Handoffs are built by heuristics from the session's own event stream, never from transcripts and never by an extra model call.

Anyone who can fetch the repository can read this state, including everyone in the world for a public repository. The setup screen states this before anything is published, and doctor warns when the remote is public. One redaction module serves both directions, so the outbound list and the inbound rules stay aligned. The source is at github.com/RyanNorouzi/synchrobuilder.

Claude Code delivers a hook's additionalContext by wrapping it in a system reminder that is inserted where the hook fired. It does not appear as a chat message in the interface, and Claude Code adds no "untrusted" marker of its own. Everything Synchrobuilder injects that did not come from your machine was typed by a teammate, by a teammate's Claude, or by anyone with push access to the remote. So the labelling is the plugin's job.

Identifiers (handle, device, branch, path, task id, symbol, timestamp) are validated against strict rules or withheld entirely; they are never "cleaned". Free text (task summaries, message bodies, handoff items, board titles) goes through the sanitizer on the reader's side, at sync time, because a compromised writer bypasses any writer-side step. The sanitizer strips terminal escapes, control and zero-width characters, neutralizes code fences, headings and role labels such as Human: at the start of a line, defangs URLs, redacts secrets, caps each field, and HTML-escapes the rest. Hooks only concatenate strings that were sanitized earlier, which keeps them inside their time budget.

Every injection is one string with a factual preamble, a begin marker, the entries, and an end marker. Both markers carry a 16-hex nonce generated in the hook process per injection and never stored. Every teammate line starts with two spaces and a pipe, every plugin-generated label with two spaces and an at sign, so no teammate text can start at column 0. The literal marker tokens are replaced if they appear inside a message. A final check confirms exactly one begin and one end marker with the same nonce and no line at column 0; if it fails, the hook prints nothing.

Every hook is declared in exec form: "command": "node" with "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "<verb>"]. Claude Code spawns the executable directly with no shell involved. One entry point dispatches on the verb, and the plugin ships plain ESM with no dependencies and no build step, so what is in the repository is what runs. The two edit hooks match Edit|Write|NotebookEdit; edits made through Bash are not covered in v1.

Session start, the prompt hook and the pre-edit hook get 400 ms each, post-edit 1.5 s, stop 2 s and session end 1 s; a watchdog ends the process with no output when a hook overruns its budget. Measured end to end by spawning the real dispatcher: 21 to 26 ms per hook on macOS. A Windows CI runner is roughly four times slower, which is why the two short budgets are 400 ms rather than the 120 ms they started at. CI runs the same tests on Windows and Linux, but no per-OS timings are recorded in the ledger. The same runs against the real Claude Code CLI showed all six events firing in exec form in a headless session on Claude Code 2.1.218, the post-edit guard note reaching Claude in the same turn, and a missing node producing a non-blocking hook error rather than a blocked session.

Mute is a local flag file that the guard hook checks first, because the Claude Code docs say there is no way to disable an individual hook. The muted guard still runs and prints nothing.

Synchrobuilder is not Anthropic's Agent Teams and not cross-session messaging. Agent Teams is one person orchestrating several Claude Code instances on one machine from one lead session; it is experimental, off by default, local to one home directory, and its team config is removed when the session ends. Cross-session messaging lets one person's Claude Code sessions talk to each other, on one machine through files and a per-user socket or named pipe, and between machines through Anthropic's servers over a Remote Control connection tied to a single claude.ai sign-in. Synchrobuilder is designed for several people, each with their own Claude Code and their own account or provider, on their own machines, sharing durable state that outlives every session, through a remote they already have, with no Anthropic-side relay. The two can coexist. One convention is reused: an incoming message is framed as coming from another session, not from the user, which is the model for the wrapper above.

The closest prior art is claude-code-relay (MIT). Synchrobuilder takes the shape of its client with credit: hooks that read only a local snapshot, a local journal of session events, an outbox that survives being offline, a background worker that does all network work, advisory collisions with a staleness ladder, and a 140-character derived objective. It replaces Relay's hosted hub with the git remote, its /bin/sh wrapper with exec-form Node, and its bundled TypeScript with plain source, and it sends neither reply prose nor diff hunks. No code is copied; if that changes, the MIT notice and a credit line go in the file header.

Read the Security page for the threat model, the Commands page for what each command does, and the Install page for prerequisites.