How to Sync Cursor Rules Across Machines Without Git Conflicts

To sync Cursor rules across machines without git conflicts, separate team repository rules from personal developer guidelines. Store shared project rules in version-controlled .cursor/rules/*.mdc files, keep personal developer preferences outside dirty git worktrees using an external sync layer, and avoid brittle file symlinks that break across macOS and Linux path conventions.

Why Does Syncing Cursor Rules Across Machines Cause Git Conflicts?

Syncing Cursor rules causes git conflicts when developers commit personal editor instructions directly into a shared repository's .cursor/rules/ folder or attempt to synchronize active git worktrees across multiple computers. Because different machines and team members touch rule files simultaneously, unstaged changes block git pull operations, create merge conflicts on feature branches, and pollute shared pull requests.

When Cursor introduced modular project rules in version 0.40, it replaced the monolithic root .cursorrules file with discrete .cursor/rules/*.mdc documents. According to the official Cursor Project Rules Documentation: “Project rules are stored in .cursor/rules in your repository. They allow you to provide context and instructions that are specific to your project.”

However, developers frequently treat this directory as a catch-all dumping ground for both team-wide architectural rules and personal productivity habits. If you add a personal code formatting rule or an uncommitted testing guideline on your laptop, switching to your desktop or remote devbox immediately breaks your workflow:

• Dirty Git Worktrees: Modifying a rule file on laptop A leaves uncommitted changes in your branch. Running git checkout or git pull on laptop B fails with errors like error: Your local changes to the following files would be overwritten by merge. If you work with Git Worktrees, each worktree requires a separate copy of the rule folder.
• Pull Request Pollution: Personal rules committed to feature branches get pushed to GitHub, triggering code review friction with teammates who do not share your exact editor configuration or preferred AI prompts.
• Context Window Bloat: If you bundle multiple personal rules into the repository, each active file consumes between 500 and 1,200 tokens from the model's context budget. When multiple rules load concurrently, the agent loses focus on project-critical constraints.

Where Does Cursor Store Rules on macOS, Linux, and Windows?

Cursor stores project-specific rules in the .cursor/rules/ directory located in the workspace root on all operating systems. Global user-level instructions are saved inside the application's private user configuration directory—under ~/Library/Application Support/Cursor/User/ on macOS, ~/.config/Cursor/User/ on Linux, and %APPDATA%\Cursor\User\ on Windows—which is never version-controlled by git.

Understanding where these files live across your development machines is the first step toward clean synchronization. The table below outlines how Cursor handles rule files, global settings, and internal workspace states:

Cursor versions 0.40 and newer parse modular .cursor/rules/*.mdc files ahead of any legacy root .cursorrules file. Each rule file contains YAML frontmatter defining its description, target file globs, and whether it applies automatically. To prevent syntax errors that cause Cursor to silently ignore your rules, review our diagnostic guide on fixing Cursor rules not working.

Repository Rules vs Personal Guidelines: The Two-Tier Architecture

Engineering teams avoid multi-machine rule drift by establishing a strict two-tier architecture: team-level repository rules are checked into Git, while developer-level personal workflows stay decoupled in an external library.

When both levels share the same filesystem directory, synchronization becomes fragile. Here is how high-velocity developers structure the boundary:

Below is a production example of a clean Tier 1 project rule stored in .cursor/rules/api-conventions.mdc. It maintains an indexing size well below Cursor's 24 KB background embeddings cap:

---
description: Enforce strict Zod v3 validation and typed error handling in API routes
globs: "src/app/api/**/*.ts"
alwaysApply: false
---

# API Route Conventions

- Validate all incoming request payloads using Zod schemas located in `@/schemas`.
- Never return untyped `NextResponse.json({ error })`. Always use the standard ApiResponse<T> wrapper.
- Handle database exceptions with explicit status codes (400 for validation errors, 404 for missing entities, 500 for unhandled exceptions).
- Keep handler functions under 80 lines; extract complex business logic to `@/services`.

Why Do Symlinks and Cloud Storage Break Cursor Rules Across Computers?

Using symbolic links or cloud folder sync (such as iCloud Drive, Dropbox, or OneDrive) to share .cursor/rules breaks because cloud background sync does not handle rapid editor file locks and atomic file saves. When Cursor writes temporary rule state or indexes embeddings, cloud synchronization generates conflicted duplicate files, corrupts symlink paths across different operating system filesystems, and triggers continuous reload thrashing.

Developers often attempt to synchronize rules by creating symlinks from their repository to a central dotfiles directory or cloud folder:

# The brittle symlink approach (DO NOT USE in production)
ln -s ~/Dropbox/my-cursor-rules/ .cursor/rules

This approach fails in four distinct ways across real-world developer setups:

1. Symlink Portability Failures: Symlinking .cursor/rules to an external directory causes git to track broken symlinks when repository worktrees are cloned across differing operating system paths. A symlink pointing to /Users/omer/... on macOS fails completely when pulled on a Linux workstation or Windows WSL environment.
2. Conflicted Copy Storms: Cloud storage services like iCloud Drive and Dropbox corrupt Cursor rule indexing by generating duplicate conflict files during simultaneous editor write events. When Cursor recalculates rule embeddings, file locking causes cloud sync engines to emit files named api-conventions (Conflicted Copy 2026-10-03).mdc, breaking YAML parsing.
3. Git Worktree Collisions: If you use agent instructions across repos and worktrees, each branch worktree shares the same root folder structure. Symlinks cause changes in one worktree to bleed unpredictably into active branches, breaking branch isolation.
4. Zero Cross-Tool Support: A symlinked Cursor directory does nothing for other AI coding assistants. If you also use Windsurf, Claude Code, or Codex, you must maintain separate symlinks for .windsurfrules, ~/.claude/skills, and ~/.codex/skills, multiplying your maintenance overhead. Compare these differences in our guide on Cursor rules vs Windsurf Cascade rules.

The Multi-Machine Sprawl Scenario: A Broken Deploy Across Two Laptops

You spend your afternoon fine-tuning an API schema validation rule in .cursor/rules/api-conventions.mdc on your office MacBook, teaching the Cursor agent to strictly adhere to Zod v3 validation patterns and OpenAPI specs. That evening, you open the same repository on your personal desktop or secondary laptop to test an urgent bug fix on a separate branch. When you ask Composer to scaffold a new endpoint, the agent immediately writes outdated manual type assertions and legacy middleware logic. The new rule was never pushed to the remote branch because committing work-in-progress guidelines into a shared team repository would trigger merge conflicts and pollute code reviews. Your carefully crafted instruction was trapped on the other machine, leaving you to manually re-type the prompt from memory or pull stale git stashes.

How Can You Sync Personal Cursor Rules Globally Without Polluting Git?

You can sync personal Cursor rules globally by using an external agent skill and rule manager that decouples your personal library from the project repository. Instead of modifying .cursor/rules inside git worktrees, an external manager synchronizes your instructions across computers in the background and injects them into Cursor sessions via hotkeys, CLI bridges, or MCP servers.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Rather than wrestling with dotfiles or dirty git trees, Prompttly provides an automated multi-machine workflow tailored specifically for AI power users:

• Sub-200ms Hotkey Palette on Mac: Access your entire personal prompt and skill library instantly from any application using a native keyboard shortcut. Search rules, preview frontmatter, and insert instructions directly into Cursor Composer without opening browser tabs or copying text files.
• Two-Way Filesystem Synchronization: Prompttly monitors your local skill directories and mirrors updates to the cloud with automatic version history. Edit an instruction on your laptop, and your desktop reflects the updated rule within seconds.
• Cross-Agent Portability: Format rules once and deploy them everywhere. Prompttly translates your library into .cursor/rules, Claude Code SKILL.md folders, and OpenAI Codex configurations, eliminating repetitive prompt rewriting. Learn more about cross-machine workflows in our guide to syncing prompts across laptops.
• Team Sharing Without Git Noise: Share verified coding standards with teammates through cloud workspaces or connect your library directly to any agent using the Custom Instructions Generator or Claude Skill Creator.

Frequently Asked Questions About Syncing Cursor Rules

Related Resources & Next Steps

Explore additional architectural guides and synchronization tools from the Prompttly resources hub:

• How to Fix Cursor Rules Not Working: Comprehensive debugging guide for glob matching, YAML frontmatter errors, and rule precedence.
• Cursor Rules vs Windsurf Cascade Rules: Architectural comparison of IDE instruction formats and token budget economics.
• Agent Instructions Across Repos: How to manage .cursor/rules and AGENTS.md across git repositories and worktrees.
• Sync Prompts Across Laptops: Practical strategies for moving AI rules, skills, and prompts between work and personal computers.