Migrating from Cursor or Windsurf

Quickly migrate your custom rules from Cursor or Windsurf to Sypha. The process typically takes just a few minutes per project.

Last Updated: March 2026

Why Sypha's Rules System?

Sypha simplifies AI configuration while adding powerful new capabilities:

• Simple format: Plain Markdown files—no YAML frontmatter or GUI configuration required
• Mode-specific rules: Different rules for different workflows (Code, Debug, Ask, custom modes)
• Better version control: All configuration lives in your repository as readable Markdown
• More control: Custom modes let you define specialized workflows with their own rules and permissions

Quick Migration Guide

Choose your current tool:

• Migrating from Cursor → Skip to Cursor migration
• Migrating from Windsurf → Skip to Windsurf migration

Migrating from Cursor

What's Different in Sypha

Migration Steps

1. Identify your rules:

ls -la .cursor/rules/        # Project rules
ls -la .cursorrules          # Legacy file (if present)

2. Create Sypha directory:

mkdir -p .sypha/rules

3. Convert .mdc files to .md:

For each file in .cursor/rules/, remove the YAML frontmatter and keep just the Markdown content.

Cursor format:

---
description: TypeScript coding standards
globs: ["*.ts", "*.tsx"]
alwaysApply: false
---

# TypeScript Standards
- Always use TypeScript for new files
- Prefer functional components in React

Sypha format:

# TypeScript Standards

- Always use TypeScript for new files
- Prefer functional components in React

4. Migrate in one command:

# Copy all files
for file in .cursor/rules/*.mdc; do
  basename="${file##*/}"
  cp "$file" ".sypha/rules/${basename%.mdc}.md"
done

# Then manually edit each file to remove YAML frontmatter (the --- section at the top)

5. Migrate global rules:

• Open Cursor Settings → General → Rules for AI
• Copy the text content
• Save to ~/.sypha/rules/cursor-global.md

6. Handle legacy .cursorrules:

cp .cursorrules .sypha/rules/legacy-rules.md

Converting Cursor's globs Patterns

Cursor's globs field specifies which files a rule applies to. Sypha handles this through mode-specific directories instead.

Cursor approach:

---
globs: ["*.ts", "*.tsx"]
---
Rules for TypeScript files...

Sypha approach (Option 1 - Mode-specific directory):

mkdir -p .sypha/rules-code
# Save TypeScript-specific rules here

Sypha approach (Option 2 - Custom mode):

# .syphamodes (at project root)
- slug: typescript
  name: TypeScript
  roleDefinition: You work on TypeScript files
  groups:
      - read
      - [edit, { fileRegex: '\\.tsx?$' }]
      - ask

Then place rules in .sypha/rules-typescript/

Flattening Nested Cursor Rules

Cursor supports nested .cursor/rules/ directories. Sypha uses flat structure with descriptive names:

# Cursor: .cursor/rules/backend/server/api-rules.mdc
# Sypha: .sypha/rules/backend-server-api-rules.md

Migrating from Windsurf

What's Different in Sypha

Migration Steps

1. Identify your rules:

ls -la .windsurf/rules/      # Project rules
ls -la .windsurfrules        # Legacy file (if present)

2. Create Sypha directory:

mkdir -p .sypha/rules

3. Copy files directly (already Markdown):

cp .windsurf/rules/*.md .sypha/rules/

4. Migrate global rules:

cp ~/.codeium/windsurf/memories/global_rules.md ~/.sypha/rules/global-rules.md

5. Handle legacy .windsurfrules:

cp .windsurfrules .sypha/rules/legacy-rules.md

6. Split large rules if needed:

If you had rules approaching the 12,000 character limit, split them:

# Instead of one large file:
# .windsurf/rules/all-conventions.md (11,500 chars)

# Split into focused files:
# .sypha/rules/api-conventions.md
# .sypha/rules/testing-standards.md
# .sypha/rules/code-style.md

Converting Windsurf's Activation Modes

Windsurf configures activation through the GUI. In Sypha, file organization replaces GUI configuration:

Example - Converting a Glob rule:

If you had a rule in Windsurf with Glob mode set to *.test.ts, create a custom test mode:

# .syphamodes (at project root)
- slug: test
  name: Testing
  roleDefinition: You write and maintain tests
  groups:
      - read
      - [edit, { fileRegex: '\\.(test|spec)\\.(ts|js)$' }]
      - ask

Then place the rule in .sypha/rules-test/

AGENTS.md Support

All three tools support the AGENTS.md standard. If you have one, it works in Sypha automatically:

# Verify it exists
ls -la AGENTS.md

# That's it - Sypha loads it automatically (enabled by default)

Important: Use uppercase AGENTS.md (not agents.md). Sypha also accepts AGENT.md (singular) as a fallback.

Note: Both AGENTS.md and AGENT.md are write-protected files in Sypha and require user approval to modify.

Understanding Mode-Specific Rules

This is Sypha's unique feature that replaces both Cursor's globs and Windsurf's activation modes.

Directory Structure

.sypha/rules/              # Apply to ALL modes
.sypha/rules-code/         # Only in Code mode
.sypha/rules-debug/        # Only in Debug mode
.sypha/rules-ask/          # Only in Ask mode
.sypha/rules-{custom}/     # Only in your custom mode

Real-World Example

From Cursor:

---
description: Testing best practices
globs: ["**/*.test.ts", "**/*.spec.ts"]
---
# Testing Rules
- Write tests for all features
- Maintain >80% coverage

To Sypha:

# 1. Create test mode directory
mkdir -p .sypha/rules-test

# 2. Save rule as plain Markdown
cat > .sypha/rules-test/testing-standards.md << 'EOF'
# Testing Rules
- Write tests for all features
- Maintain >80% coverage
EOF

# 3. Define the mode (optional - creates a custom mode)
# Add to .sypha/config.yaml:
# modes:
#   - slug: test
#     name: Test Mode
#     groups: [read, edit, ask]

Post-Migration Checklist

After migration:

• Verify rules loaded: Click law icon (⚖️) in Sypha panel
• Test rule application: Ask Sypha to perform tasks following your rules
• Organize rules: Split large files, use clear names
• Set up mode-specific rules: Create directories for specialized workflows
• Update team docs: Document new .sypha/rules/ location
• Commit to version control: git add .sypha/
• Remove old directories: Delete .cursor/ or .windsurf/ folders once verified

Troubleshooting

Rules Not Appearing

Check file location:

ls -la .sypha/rules/      # Project rules
ls -la ~/.sypha/rules/    # Global rules

Verify file format:

• Can be any text file extension (.md, .txt, etc.) - binary files are automatically filtered out
• Remove all YAML frontmatter from Cursor files
• Ensure files are not cache/temp files (.cache, .tmp, .log, .bak, etc.)

Reload VS Code:

• Cmd+R (Mac) or Ctrl+R (Windows/Linux)
• Or: Command Palette → "Developer: Reload Window"

Cursor Metadata Lost

Cursor's globs, alwaysApply, and description don't transfer automatically. Solutions:

• For file patterns: Use mode-specific directories or custom modes
• For always-on rules: Place in .sypha/rules/
• For context-specific rules: Use clear file names and organization

Windsurf Activation Modes Lost

Windsurf's GUI activation modes (Always On/Glob/Model Decision/Manual) aren't stored in files. Solutions:

• Before migrating: Document each rule's activation mode
• After migrating: Organize files accordingly in Sypha

Nested Rules Flattened

Cursor's nested directories don't map to Sypha. Flatten with descriptive names:

# Bad: .cursor/rules/backend/api/rules.mdc
# Good: .sypha/rules/backend-api-rules.md

AGENTS.md Not Loading

• Verify filename: Must be AGENTS.md or AGENT.md (uppercase)
• Check location: Must be at project root
• Check setting: Verify "Use Agent Rules" is enabled in Sypha settings (enabled by default)
• Reload: Restart VS Code if needed

Advanced: Creating Custom Modes

For complex workflows, define custom modes with their own rules and permissions:

# .syphamodes (at project root)
- slug: review
  name: Code Review
  roleDefinition: You review code and suggest improvements
  groups:
      - read
      - ask
      # Note: No edit permission - review mode is read-only

- slug: docs
  name: Documentation
  roleDefinition: You write and maintain documentation
  groups:
      - read
      - [edit, { fileRegex: '\\.md$', description: "Markdown files only" }]
      - ask

Then create corresponding rule directories:

mkdir -p .sypha/rules-review
mkdir -p .sypha/rules-docs

Note: .syphamodes can be in YAML (preferred) or JSON format. For global modes, edit the custom_modes.yaml file via Settings > Edit Global Modes.

Next Steps

• Learn about Custom Rules
• Explore Custom Modes
• Set up Custom Instructions
• Join our Discord for migration support

Additional Resources

Community Examples

Cursor users:

• awesome-cursorrules - 700+ examples you can adapt

Windsurf users:

• Official Rules Directory
• windsurfrules

Cross-tool:

• AGENTS.md Specification
• dotagent - Universal converter tool