sync.md

Using more than one AI coding tool? Your AGENTS.md, CLAUDE.md, and .cursorrules quietly drift apart and start contradicting each other. sync.md compares your AI instruction files by meaning — not text — and keeps them aligned, clean, and visible across your whole workspace, including nested subdirectories.

It watches AGENTS.md, CLAUDE.md, .cursorrules, and .github/copilot-instructions.md. It never modifies your source code — only the rule files themselves. No telemetry. No bundled cloud API keys.

Demo

Screenshots

Problems panel — conflicts, missing rules, and length warnings appear as normal VS Code diagnostics, grouped by file, with the sync.md source label so you always know where they came from:

AI-powered meaning comparison, not text diffing — these two files say the same thing in totally different languages/wording (German, emoji, Japanese, Chinese vs. plain English) and sync.md correctly treats them as in sync, only flagging a genuinely missing Security section:

Run "sync.md: Reconcile" from the Command Palette:

The Reconcile webview — a calm, native-feeling view of conflicts and missing rules between two files, with one-click "Copy to..." actions and a "Make consistent" button that applies every suggested fix at once:

After reconciling — the missing Security section is now written into CLAUDE.md automatically, clearly marked so you can review exactly what changed before committing:

What it does

1. Sync check — AI-powered

When two or more rule files share the same directory scope, sync.md asks a language model to compare their meaning, not their text. Files that say the same thing in different words are correctly treated as in sync — only genuine contradictions (conflicts) or rules present in one file but entirely absent from another (missing) get flagged.

Diagnostics appear inline (squiggles) and in the Problems panel, labeled so you always know they came from sync.md:

• Conflicts with <other file>: <topic>. (Warning)
• Missing vs <other file>: <topic>. (Warning)

Because it compares meaning, the same rules written in German, Japanese, emoji, or plain English are all recognized as equivalent — it only flags what's genuinely different.

For each conflict, the model also recommends which version to keep ("Suggested: keep <file> — <reason>"), grounded in real project evidence where available — for example, an actual package.json test script can settle a disagreement about which test command to run. If the model can't judge confidently, no recommendation is shown and the first file's wording is used as a deterministic fallback.

Run sync.md: Reconcile to open a calm, native-feeling webview showing conflicts and missing rules grouped clearly, with per-item Copy to… actions and a Make consistent button that applies every suggested fix at once. You can override any individual item with its own Use this button.

The check re-runs on save and on file open (debounced ~800ms) and caches the last result per file pair — it only calls the model again when a watched file's content actually changed.

Heads up: the sync check is AI-powered and needs a language model — either GitHub Copilot (default) or a local model via LM Studio / Ollama. Without one, the length and active-file features still work; the sync check politely tells you it needs a model rather than falling back to unreliable text diffing.

Model options:

• auto (default) — VS Code's Language Model API, typically backed by GitHub Copilot.
• local — an OpenAI-compatible endpoint such as LM Studio or Ollama, for a fully offline setup with no cloud dependency.

2. Length hygiene

If a rule file exceeds rulesSync.maxLines non-empty lines (default 200), an Information diagnostic on line 1 suggests splitting it into nested rule files. No AI required.

3. Active-file indicator

A status bar item shows which rule file governs the file you're currently editing, using "nearest file wins" (the closest rule file walking up the directory tree): Rules: <relative path>, or Rules: none. Click it to open that file. Updates as you switch editors. No AI required.

Configuration

Enabling a local model (fully offline sync checks)

1. Install LM Studio or Ollama and start its local server (OpenAI-compatible /v1/chat/completions endpoint).
2. Set rulesSync.modelProvider to "local".
3. If your server isn't on http://localhost:1234/v1, set rulesSync.localEndpoint accordingly.
4. Save a rule file (or run sync.md: Re-scan workspace) to trigger a check against the local model.

Commands

• sync.md: Reconcile — opens the conflict/missing-rules webview for the current (or first available) out-of-sync file pair.
• sync.md: Re-scan workspace — forces a fresh scan and AI check (the model is only re-called if content changed since the last check).

Design

The reconcile webview reads VS Code theme variables exclusively (it never hardcodes colors), so it looks native in both light and dark themes. It uses a restrained three-size type scale, hairline 1px borders instead of boxes or shadows, ~8px rounded corners, and a single accent color reserved for the primary Make consistent button — for a calm, spacious, native feel.

Contributing / building from source

See DEVELOPMENT.md for running the extension (F5), packaging with vsce, the file structure, and a walkthrough of every edge case in the sample/ workspace.