Stop agent drift before it becomes a merge conflict.
A local coordination protocol for AI agents that share resources.
English · 中文
AI coding agents fail not because they write bad code — but because they continue from different realities.
- Agent A owns
shared-config.ts. Agent B edits it anyway. Neither knows. - A checkpoint goes stale. Another agent resumes from it and builds on wrong assumptions.
- A handoff loses the blockers, risks, and review state the previous agent built up.
- A hard constraint says "don't touch the auth module." The agent touches it. Nothing stops it.
By the time you notice, the damage is a merge conflict — or worse, silently wrong code in production.
SyncPoint checks whether an agent's continuation path is safe before the agent proceeds. If it isn't, SyncPoint blocks — not with a warning in a prompt, but with a hard protocol gate the agent cannot skip.
Two agents claim the same file. SyncPoint creates a SyncGate — a hard stop that neither agent can ignore.
# Start the server
pnpm build && pnpm --filter syncpoint-server dev
# Terminal A — agent-a claims a file exclusively
syncpoint claim src/shared-config.ts --agent agent-a --mode exclusive
# Terminal B — agent-b tries to claim the same file
syncpoint claim src/shared-config.ts --agent agent-b --mode exclusive
# → BLOCKED. agent-b sees who holds the lock and why.
# See the full state
syncpoint status
# → Shows: agent-b is blocked because agent-a has an exclusive claimThe blocked agent doesn't just get an error message. SyncPoint creates a SyncGate — a synchronization barrier that both agents can see. The gate stays open until the conflict is explicitly resolved. Neither agent can silently proceed.
Agent-a checkpoints mid-task. Meanwhile, agent-b changes related dependencies. When agent-a resumes, SyncPoint detects the stale context.
# agent-a saves progress
syncpoint checkpoint --agent agent-a --summary "Auth module halfway done"
# ... time passes, other agents make changes ...
# agent-a tries to resume
syncpoint resume --agent agent-a
# SyncPoint checks:
# - Is the checkpoint still fresh?
# - Did other agents touch related resources?
# - Are there new constraints or blockers?
#
# If stale → warnings and blockers are injected into the resume output.
# The agent sees: "Your assumptions may be outdated."Without SyncPoint, the agent resumes from a stale snapshot and silently produces code based on assumptions that no longer hold. With SyncPoint, the staleness is caught at the resume boundary.
Agent-a finishes frontend work and hands off to agent-b for backend. SyncPoint transfers not just a text summary, but a complete structured state.
# agent-a hands off to agent-b
syncpoint loop handoff \
--task <taskId> \
--from agent-a \
--to agent-b \
--context "Login page complete. API uses JWT, token expiry 1h"
# agent-b resumes — receives:
# ✓ Context snapshot (working resources, completed work, blockers)
# ✓ Constraint state (active rules, do-not-touch scopes)
# ✓ Resource ownership (what agent-a claimed, what's released)
# ✓ Unresolved gates (any pending sync obligations)A handoff is not "send a message about what I did." It is a structured state transfer — task context, resource ownership, active constraints, and unresolved blockers, all packaged together. The receiving agent gets a complete reality projection, not a text summary that might miss critical details.
Set a constraint that no agent may touch a protected scope. SyncPoint enforces it at the execution boundary — not in the agent's prompt.
# Add a hard constraint via project memory
syncpoint project-memory add \
--content "Auth module under audit — do not modify" \
--kind hard_constraint \
--applies-to '{"files":["src/auth/**"]}' \
--severity blocking \
--validator-type resource_forbidden
# Any agent that tries to claim or modify files under src/auth/ gets blocked
syncpoint claim src/auth/middleware.ts --agent rogue-agent
# → BLOCKED by Constraint Evaluation
# Verify constraints
syncpoint constraint check --action resume --task <taskId> --agent <agentId>The key difference: constraints live in SyncPoint's execution layer, not in the agent's prompt. An agent prompt can be ignored. A SyncPoint constraint cannot. This is the difference between "please don't touch this" and "you physically cannot touch this."
# Install dependencies and build
pnpm install
pnpm build
# Initialize SyncPoint in your project
syncpoint init
# Run the demo — shows collision detection in action
syncpoint demo
# Stop at the blocked state to inspect
syncpoint demo --stage blocked
syncpoint statusWithout global install:
node packages/syncpoint-cli/dist/main.js demo
node packages/syncpoint-cli/dist/main.js statusCreating a manifest file in .syncpoint/agents/ registers the agent automatically:
# .syncpoint/agents/my-agent.yml
version: 1
name: my-agent
provider: auto_detect
profile: general
role: executorsyncpoint agent list # See all declared agents
syncpoint agent diagnose # Check for issuesSyncPoint exposes the same protocol through MCP for editor agents.
{
"mcpServers": {
"syncpoint": {
"command": "node",
"args": ["<SYNCPOINT_REPO>/packages/syncpoint-mcp/dist/main.js"],
"env": {
"SYNCPOINT_PROJECT_ROOT": "<YOUR_PROJECT_ROOT>"
}
}
}
}{
"servers": {
"syncpoint": {
"type": "stdio",
"command": "node",
"args": ["<SYNCPOINT_REPO>/packages/syncpoint-mcp/dist/main.js"],
"env": {
"SYNCPOINT_PROJECT_ROOT": "${workspaceFolder}"
}
}
}
}SyncPoint enforces boundaries through five protocol primitives:
| Primitive | What it does |
|---|---|
| ResourceClaim | Agent declares "I will touch these resources" — overlapping claims create blockers |
| SyncGate | A hard stop — cannot continue until the gate is resolved |
| CheckpointReview | A checkpoint that requires approval before another agent can resume from it |
| Operation | A tracked change checked for ownership, conflicts, and constraints before apply |
| Wake | A sync obligation — notifies an agent to review, approve, or acknowledge |
The core loop: pause → sync → resume.
When an agent tries to continue, SyncPoint checks:
- Do working resources overlap a protected scope? → blocked
- Is there an unresolved ownership conflict? → blocked
- Is there an open gate or pending review? → blocked
- Is the checkpoint stale? → blocked
If everything is clean, the agent continues. If not, the specific blocker is surfaced with the reason and what needs to happen to unblock.
| It is not | Why |
|---|---|
| Agent runner | Does not call model APIs or run autonomous loops |
| Workflow builder | Does not build DAGs or visual flows |
| File lock daemon | Protocol-level enforcement, not OS-level (see enforcement design) |
| Memory product | Project memory supports synchronization, not generic recall |
SyncPoint is the layer agents call before they continue.
packages/
├── syncpoint-kernel # Pure types, validators, state machines, errors
├── syncpoint-context # Memory, reality projection, context policy
├── syncpoint-governance # Constraint evaluation, checkpoint review, wake engine
├── syncpoint-adapters # Agent manifests, negotiation, orchestration, runtime
├── syncpoint-core # Facade — re-exports kernel, context, governance, adapters
├── syncpoint-server # Application services, SQLite, tRPC, SSE
├── syncpoint-cli # Operator CLI
├── syncpoint-mcp # MCP adapter for editor AI agents
├── syncpoint-sdk # Typed client for integrations
├── syncpoint-plugin-generic-agent # Generic resource plugin
└── vscode-extension # Sync View panel
Dependency order: kernel → context → governance → adapters → core → server → cli, mcp, sdk
| Layer | Technology |
|---|---|
| Language | TypeScript |
| Runtime | Node.js |
| Package manager | pnpm workspaces |
| Database | SQLite + Drizzle ORM |
| API | tRPC |
| Validation | Zod |
| Tests | Vitest |
| Editor integration | MCP + VS Code extension |
| Document | Best for |
|---|---|
docs/core-synchronization.md |
Protocol primitives and invariants |
docs/reality-runtime.md |
Layered reality architecture |
docs/constraint-runtime.md |
Constraint evaluation rules and enforcement |
docs/ARCHITECTURE.md |
Layer boundaries and code placement |
docs/beyond-code.md |
SyncPoint for non-code resources |
docs/local-operations-guide.md |
Operating SyncPoint with CLI, MCP, server |
docs/migration-guide.md |
Migrating to manifest-based agent registration |
| Scenario | Directory | What it shows |
|---|---|---|
| File conflict | examples/conflict |
Two agents claim the same file — blocked |
| Stale resume | examples/stale-resume |
Resume from outdated checkpoint — warned |
| Handoff | examples/handoff |
Structured context transfer between agents |
| Review gate | examples/review-gate |
Checkpoint requires approval — blocked |
For the interactive version, run syncpoint demo.
SyncPoint helps multiple AI agents stop, align, and continue safely.