Omniscio

Agent Instructions Sync

A per-project background job that keeps your canonical CLAUDE.md (or AGENTS.md) mirrored to the other filenames agents look for, with drift detection, a conflict resolver, an inbox alert, and two ways of handling the copies in git.

On this page

What it is

A per-project background job that takes the instructions file Claude Code reads on every turn — your CLAUDE.md — and automatically keeps copies of it at the other filenames that other agents look for: AGENTS.md (used by Codex, Gemini, Cursor, Factory, and other "agent-aware" tools that have settled on AGENTS.md as the cross-vendor convention), GEMINI.md (Gemini CLI), .cursorrules (Cursor's legacy file), .clinerules/base.md (Cline), .github/copilot-instructions.md (GitHub Copilot), and .windsurfrules (Windsurf).

The point is that you maintain one source-of-truth file (your CLAUDE.md, which we'll call the canonical from here on), and every other agent in the project sees the same rules without you having to copy-paste them N times or remember to keep N files in sync. You can also flip the canonical to AGENTS.md instead, in which case CLAUDE.md becomes a mirror — the direction is your call.

The feature is off by default. Default Claude Code users see no behavior change: no new files appear in their projects, nothing gets written, the sidebar looks the same. You opt in once in Settings, pick the file list, and the sync runs from then on.

Why this exists

The world has not converged on one filename for "instructions that every AI agent in this project should follow." Claude Code reads CLAUDE.md. The newer agent-aware tools (Codex, Gemini, Cursor, Factory…) have settled on AGENTS.md. Cursor's legacy file is .cursorrules. Cline reads .clinerules/base.md. GitHub Copilot reads .github/copilot-instructions.md. Windsurf reads .windsurfrules. Gemini CLI reads GEMINI.md. If you work in a project with more than one agent — even just Claude Code + your editor's Copilot — you have either (a) two copies of the same rules to keep in sync by hand, or (b) one of them is stale.

This feature collapses the "by hand" problem into one click in Settings. You write one file; Omniscio keeps the rest in sync; you get an explicit safety dialog when something has drifted instead of a silent overwrite.

Default-off is deliberate: a user whose only agent is Claude Code shouldn't have to look at, learn about, or be surprised by any of these other files. The feature only appears in the sidebar (the "Synced mirrors" subsection) when there's actually a synced mirror to show.

Where to find it

Where to turn it on

Settings → Features → Agent Instructions Sync. The section has four controls:

  1. Enabled toggle (off by default). Every time you switch it on — here, from the command line, or from Repo Foundations setup — every covered project that has a canonical file is synced once, straight away. You do not need to press Sync now. The usual safety rules still apply: a copy someone may have edited is refused and flagged, never overwritten.
  2. Projects to sync — shown while sync is on: every real project, by name, with its own tick box, no matter which project you have open. Untick a project to leave it completely alone while every other project keeps syncing. See "Switching sync off for one project" below.
  3. Canonical file — radio between CLAUDE.md (default) and AGENTS.md. Whichever you pick is the source-of-truth; the other becomes a mirror you can opt into.
  4. Mirrors — multi-select list of the other filenames. Each entry shows a friendly label after the filename: AGENTS.md (Codex, Gemini, Cursor, Factory…), GEMINI.md (Gemini CLI), .cursorrules (Cursor legacy), etc. Picking a mirror in the list is what tells Omniscio "yes, write this file too."

The canonical choice and the mirror list are global — every covered project that has the canonical present gets the same mirror list. The only per-project control is that project's tick box in Projects to sync. Projects that don't have a canonical file are silently skipped (nothing is created from nothing).

Sync now (the button at the bottom of the section) syncs every ticked project at once. It works whichever project you have open, including built-in areas like Supermail or Ask. When it finishes it shows one line per project: synced, already in sync, edited by hand and left alone, no rules file, switched off (skipped), or could not sync.

The sidebar surface

Open any project. In the right-hand Dashboard sidebar, expand the Auto Context (N) group near the bottom and look at the System Instructions sub-group (the first of the three sub-groups, listing project CLAUDE.md, project MEMORY.md, global CLAUDE.md, global MEMORY.md — see claude-files-sidebar.md for the sub-group itself). Below those four rows, if you've enabled sync and the project has any synced mirrors, you'll see a small Synced mirrors subheader (a branch icon + the label, uppercased to match the other Auto Context sub-groups) and one row per mirror with:

  • The filename on top (e.g. AGENTS.md, .cursorrules).
  • A second line with <mtime> and a small status chip: green dot in sync, blue dot out of sync (stale — see case 5 above; auto-refreshes on the next sync pass), amber dot edited externally (drift — case 6, real external edit after a recorded baseline), muted gray dot still tracked in git (tracked-in-git — the local-mode git-revert overlay on case 6), muted gray dot needs first sync (pending-baseline — case 7, day-zero state with no recorded baseline), muted gray dot manual file (case 8, no banner), or no chip if the mirror file is still missing (steady state until the first sync).

Clicking an in sync, out of sync, or manual file row opens the file in Omniscio's peek overlay so you can read it inline — same overlay as the four System Instructions rows above. The blue out of sync chip is informational only; no action is required because the watcher (or the next manual sync, or the next session spawn) will auto-refresh it. Clicking the amber edited externally chip, the muted needs first sync chip, OR the muted still tracked in git chip opens the conflict resolution dialog. edited externally and needs first sync share the same three actions and branch only the wording; still tracked in git opens a one-action mode whose only button is Stop tracking in git.

Synced-mirror rows inherit the System Instructions sub-group's bulk-select exemption: even with the Auto Context panel in multi-select mode, mirror rows render plain (no checkbox slot) and never appear in the selection count. A stray Ctrl+A + Delete that hits Always-inject and On-demand context will not touch a .cursorrules or AGENTS.md mirror.

Turning it off without losing files

Flip the Enabled toggle off. The watcher stops; no new writes happen; no existing files are deleted. Every mirror file that's already on disk stays exactly where it is, banner and all, with the body it had at the last successful sync. If you turn the toggle back on later, Omniscio re-probes and resumes — files that haven't changed in the interim go straight back to in sync, files that have changed externally during the off-period show up as edited externally and wait for your decision.

Switching sync off for one project

Use this when one project's copies are hand-managed, or hold edits you want to keep, while the rest of your projects keep syncing. Two ways to do it:

  • Settings — Settings → Features → Agent Instructions Sync → untick the project in Projects to sync (tick it again to turn it back on). It works from anywhere; you do not need to open the project first.
  • The conflict dialog — on an "edited externally" or "needs first sync" chip or inbox card, choose Stop syncing this project.

For a switched-off project, Omniscio:

  • Never writes its files — no copy refresh, no .gitignore block change, from any route (the watcher, session start, Sync now, the dialog's actions). Sync now skips it and lists it as "Switched off, so skipped."
  • Removes only its own merge hook — in committed git mode, Omniscio takes its regeneration hook out of that project's .git/hooks, because left in place the hook would keep rewriting the copies on every merge. Nothing in your working tree is touched, and it does nothing if the hook isn't there.
  • Raises no "edited outside Omniscio" alerts for it, and clears any it raised before (on the next check, and straight away when you use the dialog button).
  • Shows no "Synced mirrors" rows for it in the Auto Context panel; the doc-size scan treats its copies as ordinary always-loaded files.
  • Still briefs Codex and Gemini in that project — they get the current rules directly in their opening instructions, so they never rely on a copy sync no longer maintains.

Switching the project back on syncs it once, straight away, with the usual safety rules. A folder registered as two projects follows each project's own switch, so switching only one off lets the other keep syncing that folder. The setting behind the switch is agentInstructionsSyncExcludedProjectIds (a list of project ids, at most 500); the full rules live in agent-instructions-sync-hub-scope-contract.md.

If you want to delete the banner from a mirror so it's a "clean" file again, just edit it (or use Promote, then delete the mirror by hand). Omniscio will see the missing banner on the next sync and treat the file as manual file from then on — it won't try to recover the banner.

How it behaves

How sync works (one canonical, N mirrors)

When the canonical changes — you edit it in Omniscio, an agent edits it during a session, or you edit it in an external editor — Omniscio notices via a chokidar file watcher and runs the sync for that project. A change to a file under .claude/rules/ counts too, for the reason in step 1. For each mirror in your list, Omniscio:

  1. Reads the canonical file's body — plus, when your project has a .claude/rules/ directory, every file in it. That directory is where Claude Code reads one-file-per-topic rule files, and they are loaded on every turn exactly as CLAUDE.md is; the other agents never read .claude/ at all, so a mirror carrying only the canonical would hand Codex or Gemini a table of contents and silently drop every rule kept in a topic file. A project with no .claude/rules/ directory produces exactly the same mirror body as before.
  2. Builds a small banner (a short HTML-style comment block at the top) that says "this file is auto-managed by Omniscio, edits will be overwritten."
  3. If the mirror file doesn't exist yet → writes <banner>\n\n<canonical body> atomically (temp file + rename) and the row in the sidebar shows in sync.
  4. If the mirror file exists with the same body as the current canonical (banner stripped, hash matches) → no-op, row shows in sync.
  5. If the mirror file exists with a different body but matches the hash Omniscio last wrote into it → the canonical has moved on while the mirror was left untouched. This is stale, not drift. Omniscio auto-overwrites the mirror with the new canonical body — same as case (3) — without prompting. The row briefly shows out of sync in blue before flipping back to in sync.
  6. If the mirror file exists with a different body, and Omniscio has a recorded baseline hash for it but the body doesn't match that hash either → the file was edited externally since the last sync. Omniscio does NOT overwrite it. The row shows edited externally in amber, and clicking the chip opens the conflict resolver (see below).
  7. If the mirror file exists with a different body, but Omniscio has NO recorded baseline hash for it → this is the day-zero / first-sync state. Omniscio literally has no way to tell whether the on-disk copy is "what Omniscio wrote before it started tracking baselines" or "what the user edited." It refuses to overwrite either way. The row shows needs first sync in muted gray, and clicking the chip opens the same conflict resolver — but the wording is neutral ("first-time sync review" instead of "edited externally") because you have not done anything wrong. This happens on a fresh install with pre-existing mirrors, after a sidecar wipe, or for mirrors that were written before Omniscio started recording baselines.
  8. If the mirror file exists but has no banner → Omniscio treats this as a manual file you didn't intend for it to manage. The row shows manual file in muted gray and Omniscio never touches it. You can still take ownership later by deleting the file and re-running the sync, or by promoting the manual file to canonical.

The banner is what makes the round-trip safe: Omniscio only touches files it has previously stamped. A .cursorrules you wrote by hand before enabling sync is never silently overwritten.

The stale-vs-drift distinction (cases 5 vs 6) is what stops the "edited externally" chip from getting stuck. Omniscio remembers — in a small sidecar file at <userData>/agent-instructions-sync-state.json — the exact hash it last wrote into each mirror. When the canonical changes, every mirror that still equals Omniscio's last write is recognized as stale and auto-refreshed. A user edit, even a single byte, breaks that hash equality and we fall through to drift (case 6) so you get the safety dialog. That remembered hash is also understood under the older ways Omniscio used to compute it: a mirror nobody has touched since an Omniscio update changed the hash formula still reads as out of sync and refreshes itself, instead of being reported as edited (fixed 2026-10-10, when ten untouched mirrors were flagged at once).

The drift-vs-pending-baseline distinction (cases 6 vs 7) is the labelling split that stops the "edited externally" chip from being misleading for users who never touched the file. Both cases refuse to overwrite the mirror — that's the load-bearing safety behavior — but they say different things in the UI. drift (we have a baseline and the mirror moved away from it) keeps the accusatory amber "edited externally" wording. pending-baseline (we have no baseline for this mirror) gets neutral muted "needs first sync" wording. The on-disk decision is identical; only the chip color and the modal copy change.

The tracked-in-git overlay (a refinement of case 6) catches the most common cause of a false drift flag: in git mode local, if a mirror reads as drift but is still tracked in git, the "edit" is almost always git itself — a branch merge restoring the old committed copy over Omniscio's fresh write, which the drift guard can't tell apart from a human edit. When IMPORTANT_FILES_PROBE sees a drift row in local mode whose mirror is in git ls-files, it relabels that row tracked-in-git: a calm muted "still tracked in git" chip instead of the accusatory amber "edited externally", and clicking it opens the resolver in a one-action mode whose fix is Stop tracking in git — not discard/promote, because re-syncing a tracked copy just gets reverted by the next merge. The check is gated to local mode and to rows that are actually drift, so default and in-sync projects never pay the extra git lookup. See the git-lifecycle contract (a-tracked-mirror-in-local-mode-reads-as-tracked-in-git).

The watcher also runs an echo guard — when Omniscio itself writes a mirror, the chokidar event that fires for that write is matched against Omniscio's own outgoing-write fingerprint and discarded, so you don't get a feedback loop where Omniscio re-syncs in response to its own writes.

How copies are handled in git

The mirrors are generated from your canonical file, which makes committing them to version control awkward: a generated file that something keeps rewriting churns on every merge, and you can end up with a stale committed copy that triggers a false "edited externally" flag. Omniscio gives you an explicit choice under Settings → Features → Agent Instructions Sync — "How copies are handled in git" — with two modes. Like the rest of the feature the setting is global (no per-project override), and the git work only ever touches folders that are real git repositories — a non-git project folder is left completely alone.

Local — kept out of git (the default, recommended). Omniscio maintains a clearly-marked block in your repository's private ignore file (.git/info/exclude) that lists the copy filenames, so git ignores them. That file is never committed, so this mode never leaves your project with an unsaved change. If an older version wrote the block into your tracked .gitignore and you never saved it, Omniscio takes it back out; a block you have committed into .gitignore is yours, and Omniscio leaves it exactly as it is (remove it with your own commit if you no longer want it). If an earlier version already removed a committed block from your working copy, the file shows as modified once: run git restore .gitignore to put it back (Omniscio never writes the block into a tracked file again). The copies live only on your machine and are rebuilt from the canonical; git never tracks them, so a merge can never clobber them and a merge can never produce a false drift flag. If you already committed some copies before switching to (or starting in) this mode, the settings panel shows how many are still tracked and offers a one-click "Stop tracking copies in git" button — it runs git rm --cached on each, which removes them from git's index while keeping the file on your disk. The same one-click fix is also surfaced right on the System Instructions sidebar (next section), so you don't have to hunt through Settings — a copy stuck in this state shows a calm "still tracked in git" chip that opens the fix directly.

Committed — kept in git (opt-in). For repositories you share with people who use Codex, Gemini, or other tools without Omniscio running — they need the copy files physically present in the repo. In this mode Omniscio removes the ignore block (never one you committed) and installs a small post-merge / post-rewrite git hook that re-derives every copy from the canonical after a merge or rebase, so a merge can't leave a copy stale. The hook is written as a clearly-marked section that never overwrites an existing hook, and Omniscio skips installing it entirely if your repo manages its own hooks (for example via Husky, which sets core.hooksPath) — in that case the copies still stay merge-safe because of the stable banner (below), and you simply commit the regenerated copies alongside your canonical edits.

The stable banner. The banner Omniscio stamps at the top of every copy used to include the exact time of the write. That meant two branches that both re-synced a copy produced different files — the timestamps differed — even when the rules were identical, so every merge collided on that line. The banner no longer carries a timestamp: identical rules now produce byte-identical copies, which is what makes both git modes merge-clean. This changes nothing about drift detection — the "did someone hand-edit this?" hash has always been computed with the banner stripped off, so it never depended on the timestamp.

Drift also raises an inbox alert

The sidebar chip is passive — you only see it if you happen to be looking at that project's Dashboard, so a drifted mirror can sit unnoticed for weeks. Since 2026-08-17, Omniscio ALSO surfaces drift in your inbox. A small background watchdog (src/main/services/agent-instructions-sync/drift-watchdog.ts) checks every project's mirrors on a schedule (a couple of hours apart) and, when a mirror has read edited externally (drift) for two consecutive checks, raises one deduped inbox card — e.g. "AGENTS.md was edited outside Omniscio." The card clears itself on the next check once the mirror is no longer drifted — including cards raised before an app restart. It raises only on real drift — never a mirror git still tracks in local mode (git putting an old committed copy back is not an edit), never the neutral needs first sync (pending-baseline), the auto-healing out of sync (stale), or a manual file.

The card's Review & fix button opens the same conflict resolver the sidebar chip opens (next section): view the file, Sync now (discard the external edit and re-sync from the canonical), Stop syncing, or a Sync settings link straight to the feature's settings — so whether you spot the drift on the Dashboard or in your inbox, the one-click fix is identical.

The watchdog is READ-ONLY — it never writes a mirror, it only probes and alerts. It self-gates on the Enabled setting (turning the feature off clears the cards it raised), skips headless / test runs (AMC_INSTANCE_ID, kill-switch AMC_DISABLE_INSTRUCTION_DRIFT_WATCHDOG=1), and caps how many cards it raises per check so a many-project drift can't flood the inbox. Under the hood it is a standard inbox alert (raiseAgentAlert, dedupKey agent-instructions-drift:<mirror>:<projectId>, with a one-click action registered per inbox-alert-contract I20).

Resolving an "edited externally" or "needs first sync" conflict

When Omniscio refuses to overwrite a mirror, the dialog opens for three different reasons:

  • "edited externally" — Omniscio had a recorded baseline hash for this mirror and the on-disk body moved away from it. Something edited the file directly (the agent that file drives, a human teammate, an external editor) since the last successful sync.
  • "needs first sync" — Omniscio has no recorded baseline hash for this mirror. The on-disk body differs from the canonical, but Omniscio literally cannot tell whether you edited it or it's just the day-zero state (fresh install with pre-existing mirrors, sidecar wiped, or mirrors written before Omniscio started tracking baselines). You have not done anything wrong; this is a one-time setup step.
  • "still tracked in git" — git mode is local and the copy is still tracked in git, so a branch merge keeps restoring the old committed copy over Omniscio's write. This is not an edit you made. This mode shows ONE action — Stop tracking in git (git rm --cached, file kept on disk) — because that is the only durable fix; discard or promote of a tracked copy just gets reverted by the next merge.

The first two reasons surface the same four actions below (only the title and copy differ); "still tracked in git" replaces them with the single untrack action. Default focus is Cancel so pressing Enter never writes anything by accident.

  1. Discard edits — restore from <canonical> (red, destructive; reads "Overwrite <mirror> with <canonical>" in the pending-baseline variant). Force-overwrites the mirror with the current canonical body + a fresh banner. The external edits (or the day-zero content) are gone. Use this when the external edit was a mistake (the agent went off-script), when you've already merged the useful parts back into the canonical by hand, or — for pending-baseline — when you want the canonical to be the source of truth going forward.
  2. Promote to canonical (amber, warning). Reads the mirror body, strips the banner from it, atomic-writes the result over the canonical file. The mirror itself is left alone — but on the next sync pass it'll get a fresh banner re-applied because its body now matches the new canonical. Use this when the external edit was actually good and you want it to become the new source-of-truth.
  3. Stop syncing this mirror (ghost button). Removes this mirror from your agentInstructionsSyncMirrors setting and pushes a SETTINGS_CHANGED event so the watcher reconciles its set. The file on disk is untouched — banner and all — but Omniscio will never write it again. Use this when you've decided this particular file should be hand-managed going forward. Note this one is global — it stops the mirror in every project.
  4. Stop syncing this project (ghost button). Switches sync off for this one project only (see "Switching sync off for one project" above) and clears its drift alerts. No file is touched; every other project keeps syncing.

The dialog also shows the canonical body and the mirror body as two side-by-side <pre> blocks so you can eyeball the divergence. It's not a line-diff view — the question this dialog answers is "which copy do I want to keep?", not "what changed line-by-line?". If you need a real diff, both files are on disk; use your normal diff tool.

Important non-behavior: a promote in one mirror does NOT auto-overwrite other mirrors that were in sync with the old canonical. Those mirrors become drift conflicts at the next sync pass and each one needs its own explicit user resolution. This is conservative on purpose — silent N-way overwrite from a single promote is the kind of "I lost work" footgun the feature is specifically designed not to have.

The seven recognized mirror files

Filename Used by
AGENTS.md Codex, Gemini, Cursor (modern), Factory, other agent-aware tools
CLAUDE.md Claude Code (this is also a valid canonical — pick one)
GEMINI.md Gemini CLI
.cursorrules Cursor (legacy filename)
.clinerules/base.md Cline
.github/copilot-instructions.md GitHub Copilot
.windsurfrules Windsurf

This list is closed — adding a new agent's filename requires a code change (it's a TypeScript discriminated union, not a free-form string). The reason it's closed is the path-escape guard: Omniscio validates that every mirror path resolves under the project workdir, so we don't accidentally write ../../etc/passwd if a settings file is hand-edited maliciously. A free-form list would mean every renderer-supplied mirror gets re-validated on every sync.

  • claude-files-sidebar.md — the System Instructions sub-group of the Auto Context panel, which hosts the synced-mirrors block as a second section below its four CLAUDE.md / MEMORY.md rows.
  • project-docs-auto-injection.md — the parent Auto Context feature: search filter, the three sub-groups (System Instructions + Always-inject + On-demand context), and how .claude/docs/ files reach the agent. Different mechanism from sync — auto-injection is first-message context, not file mirroring.
  • project-docs-selection.md — bulk select / copy / delete on the other two Auto Context sub-groups. Synced mirrors inherit System Instructions' bulk-select exemption and never participate.

Last verified 2026-10-10