Keep Your CLAUDE.md, AGENTS.md, and Cursor Rules in Sync

If you’re using AI coding assistants — Claude Code, Cursor, GitHub Copilot, Codex, Windsurf — you know the context file sprawl problem.

Every project needs its own:

• CLAUDE.md for Claude Code
• AGENTS.md for OpenAI Codex (and the emerging standard)
• .cursorrules for Cursor (or .cursor/rules/)
• .github/copilot-instructions.md for GitHub Copilot
• .windsurfrules for Windsurf (or .windsurf/rules/)
• GEMINI.md for Google Gemini CLI

And they all need similar content: your coding standards, preferred patterns, project conventions, things the AI should know about how you work.

Good news: The industry is converging on AGENTS.md as a standard. GitHub Copilot, Codex, and others now read it automatically. But you might still need tool-specific files for full compatibility.

The Drift Problem

You start with good intentions. Copy your context file to a new project, tweak it for that project’s needs. Then you learn something new, update one file, and forget the others.

Three months later, you have:

• 12 versions of CLAUDE.md
• 8 versions of .cursorrules
• No idea which one has your latest preferences

Your AI assistants give inconsistent results because they’re working from inconsistent context.

The Mirror Solution

strayfiles now has file mirrors — one-way sync from a source file to multiple targets.

Here’s how it works:

1. Create a master file — One canonical version of your AI context
2. Set up mirrors — Point to every location that needs a copy
3. Sync when ready — Press S to update all targets at once

Edit the master, sync everywhere. No more drift.

Best Practice: Use a Dedicated Source File

Don’t use CLAUDE.md as your source. Instead, create a dedicated file like context.md or ai-context.md as your single source of truth, then mirror it to all the AI tool files.

Why? The source file contains strayfiles tracking metadata (frontmatter or HTML comments). When you mirror, that metadata is automatically stripped from the targets. Your AI tools see clean files without any strayfiles markup.

~/dotfiles/context.md (source with frontmatter)
         ↓ mirrors to (clean, no frontmatter)
~/project/CLAUDE.md
~/project/AGENTS.md
~/project/.cursor/rules

This keeps your AI context files clean while strayfiles tracks everything through the single source file.

Cross-Tool Sync

Different tools, same context. Mirror your master file to all formats:

~/dotfiles/context.md
         ↓ sync
~/project/CLAUDE.md
~/project/AGENTS.md
~/project/.cursor/rules
~/project/.github/copilot-instructions.md
~/project/.windsurfrules

One source of truth for all your AI assistants.

Since AGENTS.md is becoming the standard (now supported by Codex, Copilot, and others), you might simplify to just mirroring AGENTS.md plus tool-specific files for tools that don’t read it yet.

How strayfiles Handles This

When you mirror a file that’s tracked by strayfiles, the tracking metadata is automatically stripped from the target. This prevents duplicate UUIDs and keeps your targets clean.

Source file:

---
title: AI Context
strayfiles:
  enabled: true
  id: "019abc..."
---

# My Coding Standards
...

Mirrored target:

---
title: AI Context
---

# My Coding Standards
...

The strayfiles: block is removed, but your content stays intact.

Setting It Up

In the strayfiles TUI:

1. Press / to open file discovery
2. Navigate to your master context file
3. Press m → Create Mirror
4. Enter the target path
5. Repeat for each project that needs it

Or manage all mirrors from Settings → Mirrors → Manage Mirrors.

Keyboard shortcuts:

• s — Sync selected mirror
• S — Sync all mirrors
• e — Enable/disable a mirror
• d — Remove a mirror

The Workflow

Weekly or when you update your standards:

1. Edit your master context.md (or whatever you named your source file)
2. Open strayfiles
3. Go to Mirrors → Manage Mirrors
4. Press S to sync all

That’s it. Every project gets the update — clean files, no frontmatter clutter.

Beyond AI Context

Mirrors work for any file you need in multiple places:

• README.md in multiple package directories
• LICENSE files across repos
• Documentation that should live in multiple locations
• Config snippets shared between projects

Limits

• Maximum 5 mirrors per source file
• Source and target must be different files
• Targets must be unique per source

Important: One-Way Only

If you edit a target file, your changes will be lost on the next sync.

Mirrors completely overwrite targets — there’s no merge or conflict detection. Always edit the source file, never the targets.

If you accidentally edit a target, copy your changes to the source before syncing. Or disable that mirror first if you need to customize a specific target temporarily.

Try It

If you’re maintaining AI context files across multiple projects, mirrors will save you hours of copy-paste and “wait, which version is current?” frustration.

Your master file. Everywhere it needs to be. Always in sync.