agent-sync

Docs, and every skill → · this skill's page · follow @sshlg93 on X

Loads in DeepSeek Harness (dsh) with no plugin to write: it reads the Agent Skills standard directly, scanning ~/.agents/skills — where npx skills add puts this pack — at rank 500.

Several coding agents, one repository, no collisions — and each one can see what the others are doing.

agent-sync is an agent skill (plus a Claude Code plugin) that gives concurrent coding agents a coordination plane: leases with a TTL, race-free id reservation, a run journal, a cross-repo signal feed and a generated board.

• The problem
• What you get
• Requirements
• Install
• Update
• Set up a project
• Everyday use
• Configuration
• Backends
• Enforcement hooks
• Where it plugs into task-pipeline
• Limits, stated plainly
• Troubleshooting
• Uninstall
• Develop and verify

The problem

When more than one agent works a project at the same time, the coordination substrate most teams already have — a decisions log, a roadmap, a board, per-repo task files — stops being enough. Every one of those is a file edited by hand. That works for people taking turns and fails for agents working at once:

agent-sync closes exactly those, and nothing else.

The idea

Git is the record plane. The cloud is the coordination plane.

A fact that must survive is written to git first and referenced from the cloud. A fact about who is doing what right now lives in the cloud and expires. No cloud object is ever the only home of a durable fact, so your single-source-of-truth rules stay intact.

The knowledge base never decides a lease. It cannot: measured against a real instance, twelve concurrent appends to one document returned twelve successes and left three lines. Exclusion comes from something that genuinely has compare-and-swap — an atomic file create on one machine (leaseBackend: "local"), or a pushed git ref across machines (leaseBackend: "git"), where the remote's non-fast-forward rejection is the CAS. Id reservation still replays the log, which is safe because allocation is positional and every reader computes the same answer.

What you get

• Leases with a TTL — claim a task, renew automatically, steal an expired one. Exclusive across machines with leaseBackend: "git"; the tool always states which guarantee you have rather than implying the stronger one.
• The claim written through to the roadmap — one row, one cell, refused on ambiguity, and restored verbatim on release. Closing a task stays yours.
• Awareness, not just exclusion — status lists every other run's live holdings, so an agent learns who holds a task and what they are touching, instead of only that it is taken.
• Race-free id reservation — positional allocation over the log, so two agents cannot be handed one number.
• A run journal — what each run did, with commits, gate results and evidence.
• A cross-repo signal feed — filed → accepted → delivered → closed. status surfaces what landed since this run last looked, watermarked per run so it stays quiet until something actually changes.
• A generated board — machine-written, commit-stamped, and it refuses to overwrite a page a human took over.
• Enforcement hooks for Claude Code that deny an edit to a guarded register file, or a commit staging one, without a live lease.

Requirements

Install

npx @ssheleg/agent-sync install

Claude Code gets the plugin; every other agent gets the skill through the skills CLI. The duplicate plain copy in ~/.claude/skills/ is pruned afterwards, because that shadow silently serves a stale skill over the installed plugin — one channel per agent is the rule.

Restart Claude Code after installing, so it picks the plugin up.

npx github:ssheleg/agent-sync install

npx @ssheleg/agent-sync install --claude-only

npx @ssheleg/agent-sync install --agent cursor,codex

claude plugin marketplace add ssheleg/agent-sync && claude plugin install agent-sync@agent-sync

Update

Update the whole family — one package, every agent. A bundle with one member current and the rest stale is a combination nobody tested:

npx sshlg-skills update               # installed but behind — updates everything
npx sshlg-skills install              # nothing installed yet
npx --yes sshlg-skills@latest list    # what the current release of each member is

Restart your agent afterwards: skills and hooks load at session start, so the session that updates is not the session that gets the new ones.

claude plugin marketplace update agent-sync && claude plugin update agent-sync@agent-sync && npx --yes skills update agent-sync --global --yes

npx @ssheleg/agent-sync@latest install

claude plugin list | grep agent-sync
python3 ~/.claude/plugins/cache/*/agent-sync/*/skills/agent-sync/scripts/agent_sync.py --version

npx sshlg-skills install

Set up a project

Initialisation is the first command, and it asks a question rather than guessing.

/agent-sync init

The agent asks where coordination state should live — a knowledge cloud, or local files — and, for the cloud, the instance URL. Then it writes two files:

The token line is written empty. Creating the API token in your own instance and pasting it into that line is your step, and it stays yours: the tool never asks for a token in chat, never echoes one, and never passes one as a command-line argument.

Load the environment before running agents:

set -a && . ./.env.agent-sync && set +a

Then create the container the coordination log lives in, once per project, and paste the id it prints into AGENT_SYNC_OUTLINE_COLLECTION:

/agent-sync bootstrap

Verify the setup — idempotent, repairs what is missing, and names exactly one next action:

/agent-sync status

Everyday use

In an agent session you use the slash command (/agent-sync acquire ASC-072 — the verb is acquire, the same one the CLI takes); the same commands run directly against the coordinator script, which is what the hooks and CI do:

python3 "$SKILL_DIR/scripts/agent_sync.py" <command>

The shape that matters:

acquire → work on a branch → merge

Never skip the last step, including when the work failed. An abandoned lease blocks the task until its TTL expires, and the next agent cannot tell "in progress" from "crashed an hour ago". A lease is a promise to come back. merge releases for you; without a branch, release by hand.

Work on a branch, land it with merge

The integration branch is somebody else's stable base, so nothing about work in flight is committed there. acquire writes the claim through to the roadmap only on the integration branch; on any other branch it says so and keeps the holder in the coordination plane, where status already shows it to every agent — no one has to fetch your branch to see who has what, and the shared roadmap does not become the file every branch edits.

python3 "$SKILL_DIR/scripts/agent_sync.py" merge --key ASC-072 --summary "what landed"

The local integration branch is fast-forwarded to origin/<target> first, so the preflight and the merge share a base; one that has genuinely diverged is refused with both counts. Conflicts are then computed with git merge-tree before anything is touched — on conflict it names the files, changes nothing and exits non-zero, so a resolution nobody reviewed never reaches the integration branch. Then it merges --no-ff, records the merge, and releases the lease named by --key. --dry-run stops after the checks; --push pushes afterwards.

The merge log — docs/MERGES.md, configurable via mergeLog — answers the question an agent coming back from a branch cannot answer from git log alone: what landed while I was away, and was any of it near my work. Entries inside retentionDays (7) keep their detail; older ones are folded to one line each on the next write, so the file stays readable without a cron job.

python3 "$SKILL_DIR/scripts/agent_sync.py" merges          # recent detail
python3 "$SKILL_DIR/scripts/agent_sync.py" merges --all    # plus the compacted tail

This is the flow for agents sharing one repository. A project that reviews through pull requests keeps doing that — merge is then the wrong command, and finish is still the right one. Full doctrine: references/branching.md.

The lease is not the claim. The lease says who holds the task now and expires; the durable claim is the tag in git — todo (claimed: r-7f3a91), rendered from the claimTags.held template, naming the run, not a role. acquire writes that tag through and release restores exactly what was there, so one fact keeps one home.

Configuration

.claude/agent-sync.json — committed, validated against agent-sync.schema.json, starting point in agent-sync.example.json:

.env.agent-sync — gitignored, mode 600. It is looked for in this repository, then in each superproject above it (so one credentials file serves a tree of submodules), and nowhere else. AGENT_SYNC_ENV=/path/to/file names one explicitly and wins over both. Until 1.7.0 the search continued into any parent directory, so a stray file in a home or work directory silently pointed every project beneath it at one collection — check now prints which file is in force, and says when it comes from outside the repository.

AGENT_SYNC_BACKEND=outline
AGENT_SYNC_OUTLINE_URL=https://<your-instance>
AGENT_SYNC_OUTLINE_TOKEN=          # you fill this line, nobody else
AGENT_SYNC_OUTLINE_COLLECTION=     # printed by `bootstrap`

Never write a host name or a token into the config, a test, an example or a commit. If an agent offers to handle a token for you, that is the wrong answer.

A submodule's config declares only its own registers. Cross-repository facts belong to the parent repository; a service repo listing the parent's decision register is a configuration defect.

Backends

Two settings, two jobs. backend chooses the record plane — where the log, the signals and the board live. leaseBackend chooses what actually decides a lease. The knowledge base is never the second one: measured against a real instance, twelve concurrent appends to one document returned twelve successes and left three lines.

status, acquire and check all state which of the two you have, in the same words, because a lease that is not actually exclusive is worse than none: the other agent has stopped checking. runs recorded: gated follows the lease mode — never the record plane.

Adding one: read references/adapter-contract.md.

Enforcement hooks

This is the only part of the plugin that executes code on your machine. Everything else — the skill, its references — is text an agent reads. Four bash scripts, bundled in the plugin and run by Claude Code on the events below, each with a timeout (15–20s) so a hung script cannot stall a session. Read them before installing: they are short, and SECURITY.md lists every path the install touches and why.

Every hook exits immediately in projects without .claude/agent-sync.json, so installing globally changes nothing elsewhere. The PreToolUse guard can deny a tool call and never grants one that would otherwise be denied.

Details and removal: references/hooks.md.

Where it plugs into task-pipeline

agent-sync supplies stages; it does not define them. It binds to task-pipeline's stages 0, 1, 3, 4, 5, 9 and 10 — lease before the brief is committed, reconcile before code is written, reserve ids before they reach git, register file ownership for parallel groups, signal and regenerate the board at docs, release everything at acceptance. The stage numbers are stated once, in the marker at the top of the binding reference, and a check fails when a document stops agreeing with it. Wiring: references/pipeline-binding.md.

Limits, stated plainly

• Hooks are Claude Code only. On Cursor, Codex and the rest there is no PreToolUse, so nothing blocks a guarded edit; the same checks run as a self-check and the run is recorded ungated. Read the board's column rather than assuming.
• Ordering, not clocks. Document order decides who holds a lease; timestamps only expire one. Agents' clocks differ and the protocol does not depend on them.
• A reserved id that never reaches git is reported, not reclaimed. A half-written decision on a branch is not an unused number.
• fs is not cross-machine. As a record plane it is invisible to agents on another host, and the default local lease is a mutex on this one. Set leaseBackend: "git" when a fleet spans machines; the tool says which guarantee you have rather than implying the stronger one.

Troubleshooting

Uninstall

claude plugin uninstall agent-sync@agent-sync
npx --yes skills remove agent-sync --global --yes

Project files stay where they are; delete .claude/agent-sync.json, .env.agent-sync and .agent-sync/ if you want the project clean too.

Develop and verify

These run in a clone of this repository. The published npm package ships no test/ directory, so from an install they are names, not commands.

python3 test/validate.py             # manifests, version sync, no host/credential leaks
python3 test/validate.py --self-test # the validator must still be able to fail
npm test                             # both of the above

What ships: one skill (agent-sync), scripts/agent_sync.py (stdlib only), four hook scripts, the slash command, agent-sync.schema.json, and eleven reference contracts the agent loads on their own trigger rather than by default:

See CONTRIBUTING.md and CHANGELOG.md. Everyone taking part is expected to follow the Code of Conduct. Security reports: SECURITY.md.

agent-sync also ships in the sshlg-skills bundle, which installs the whole family for Claude Code, Cursor, Codex and 70+ other agents with one command.

Author

Built by ssheleg — sshlg.me

• X / Twitter — @sshlg93
• Telegram — @sshlg

License

MIT © ssheleg