Skip to main content

Sync Engine

AgentMesh sync is designed to be invisible during normal development. Most days you never run a command.

Sync triggers​

TriggerWhen it firesLatency
Runtime hooks (primary)After Claude/Codex tool calls that write files (Edit, Write, MultiEdit)~100ms p99
Watcher daemon (fallback)Direct file edits, git pull/checkout, pre-commit safety net~500ms when running
Manual CLIagentmesh sync, agentmesh applyOn demand

Hooks are installed into machine-local overlay files during agentmesh init or agentmesh install --runtime <name>.

The watcher daemon is lazy-started — it spins up when needed and exits after 30 minutes of idle time by default.

Sync pipeline​

1. Detect change (hook or watcher)
        ↓
2. Ingest from source runtime(s)
        ↓
3. Three-way structured merge (canonical ancestor + both sides)
        ↓
4. Write canonical (.ai/, AGENTS.md)
        ↓
5. Fan out to other runtime adapters (async drainer)
        ↓
6. Update agentmesh.lock

Hook execution model​

Hooks run synchronously for the canonical update + lockfile write (so the source change is captured before the hook returns), then fan out to other adapters asynchronously via a background drainer. This keeps hook overhead under 100ms while ensuring correctness.

Conflict resolution​

When concurrent edits diverge:

  1. Three-way structured merge resolves most conflicts non-destructively (~90%+)
  2. mtime last-write-wins tiebreaker for residual cases
  3. Audit trail records what happened; losing versions are preserved in cache

Review conflicts:

agentmesh doctor

Recover a losing version:

agentmesh restore skill:security-review --from codex

Acknowledge without restoring:

agentmesh ack skill:security-review

Self-write suppression​

The watcher ignores files AgentMesh itself just wrote (tracked via per-location emitted_native_sha256 hashes in the lockfile). This prevents infinite sync loops.

VCS-aware throttling​

During git operations (pull, checkout, merge), sync is deferred and runs once after the operation completes (default throttle window: 2 seconds).

Inspecting sync without writing​

agentmesh diff     # preview pending changes
agentmesh apply    # apply after reviewing diff
agentmesh sync --check   # CI dry-run (exit non-zero on any drift)

Prompt policy​

No prompts during sync. The only v0.1 install-time prompt is choosing which divergent agent memory file (AGENTS.md or CLAUDE.md) seeds initial setup. After setup, sync is bidirectional. Explicit command confirmations (install, upgrade, uninstall, restore, ack) are permitted because you typed the command.