cursor-windsurf-convert ("cuws")

Surf your AI rules from Cursor to Windsurf (and back) faster than you can say cat | cuws. 🏄‍♂️⛵

About • Why cuws? • Key Features • Quick Start • Installation • Usage • API • Developing • Contributing • Roadmap • FAQ

📖 About

cuws is a tiny but mighty Node.js CLI + library that losslessly converts rule files between Cursor (.cursor/rules/*.mdc) and Windsurf (.windsurf/rules/*.md) formats. Pipe it, script it, or call it from TypeScript—either way your rules arrive on the right shore untouched.

Windsurf shipped file‑based rules on 7 May 2025. This project exists so you can ride that wave today.

🤔 Why cuws?

• Zero friction – stream via stdin/stdout or give it paths.
• Bidirectional – Cursor ➜ Windsurf and Windsurf ➜ Cursor.
• Fast – converts a 1 kB rule in < 50 ms. Blink and you’ll miss it.
• Lossless metadata mapping – front‑matter stays intact, content unchanged.
• CI‑ready – deterministic, non‑interactive, exit codes you can trust.
• Tiny footprint – minimal runtime dependencies (gray-matter, commander, fast-glob for CLI).

✨ Key Features

🚀 Quick Start

The easiest way to use cuws without a global installation is with npx:

# Convert a single file (Cursor ➜ Windsurf) using npx
npx cursor-windsurf-convert -i .cursor/rules/auth.mdc -o .windsurf/rules/auth.md

# Pipe via stdin/stdout using npx
git show HEAD:my-rule.mdc | npx cursor-windsurf-convert --reverse > my-rule-cursor.mdc

# Convert all Cursor rules from '.cursor/rules' to Windsurf rules in '.windsurf/rules'
npx cursor-windsurf-convert -d .cursor/rules -o .windsurf/rules

# Convert all Windsurf rules from '.windsurf/rules' back to Cursor in '.cursor/rules-backup'
npx cursor-windsurf-convert -d .windsurf/rules -o .cursor/rules-backup --reverse

Alternatively, if you prefer a global installation for frequent use:

# Global install (optional)
npm install -g cursor-windsurf-convert
# Then use 'cuws' directly:
# cuws -i .cursor/rules/another.mdc -o .windsurf/rules/another.md

📦 Installation

While npx cursor-windsurf-convert ... is recommended for quick, one-off uses (see Quick Start), you can also install cuws:

As a project dependency:

# Using pnpm
pnpm add -D cursor-windsurf-convert

# Using yarn
yarn add -D cursor-windsurf-convert

# Using npm
npm install -D cursor-windsurf-convert

Then you can run it via pnpm cuws ... (if using pnpm) or add it to your package.json scripts.

Globally (for frequent use):

npm install -g cursor-windsurf-convert
# Now you can use 'cuws' directly anywhere:
# cuws --help

Node ≥ 18 required (tested on 18 & 20).

💻 Usage

CLI

cuws [options]

Programmatic API

import {
  convertString,
  convertFile,
  convertDirectory,
} from 'cursor-windsurf-convert';

// Convert a string
const cursorRuleContent = '...'; // content of a .mdc file
const windsurfRuleContent = convertString(cursorRuleContent, 'cw');

// Convert a single file
async function exampleConvertFile() {
  const outputPath = await convertFile('path/to/source.mdc', 'path/to/output.md');
  console.log(`Converted file written to: ${outputPath}`);
}

// Convert a directory
async function exampleConvertDirectory() {
  const results = await convertDirectory('path/to/source-dir', 'path/to/output-dir');
  results.forEach(result => {
    console.log(`${result.sourcePath} -> ${result.destinationPath} (${result.status})`);
  });
}

See API docs for full typings.

🛠️ Developing

1. Clone & install deps:

   hljs language-bash

   Copy

   git clone https://github.com/YOUR_ORG/cursor-windsurf-convert.git
   cd cursor-windsurf-convert && pnpm install
   

2. Link the CLI for local testing:

   hljs language-bash

   Copy

   pnpm run build # if you transpile
   pnpm link --global   # exposes `cuws` in PATH
   

3. Run tests:

   hljs language-bash

   Copy

   pnpm test
   

package.json bin field

{
  "name": "cursor-windsurf-convert",
  "version": "1.0.0",
  "bin": {
    "cuws": "dist/cli.mjs"
  },
  ...
}

The CLI file must start with #!/usr/bin/env node and be chmod +x.

🤝 Contributing

PRs welcome! Check the open issues or open a new one. Also see CONTRIBUTING.md for details.

🏄 Roadmap

• One‑file conversion
• Directory batch mode

❓ FAQ

YAML Parsing Strictness

cuws uses a strict YAML parser for the front-matter in rule files. This ensures that conversions are accurate and that your rule files adhere to valid YAML syntax. If you encounter errors related to YAML parsing (often error code E03), please check the following common pitfalls:

• Missing Colons: Ensure every key-value pair has a colon separating the key and the value.
  • Incorrect: alwaysApply true
  • Correct: alwaysApply: true
• Missing Values: Ensure that if a key has a colon, it also has a value following it.
  • Incorrect: description: (with nothing after the colon)
  • Correct: description: My rule description or remove the line if description is not needed.
• Indentation: YAML is sensitive to indentation. Ensure that your indentation is consistent and correctly represents the structure of your metadata.
• Special Characters in Unquoted Strings: If your string values contain special characters (e.g., :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `), they might need to be quoted.
  • Example: title: My Rule: A Detailed Look should be title: 'My Rule: A Detailed Look' or title: "My Rule: A Detailed Look".
  • cuws attempts to auto-quote problematic globs values during parsing, but other fields might require manual quoting if they contain special characters that could be misinterpreted by the YAML parser.

The error messages provided by cuws for YAML parsing issues will typically include the line number and a snippet from the original parser to help you locate the problem.

📄 License

MIT © 2025 Gordon Mickel

⭐ If this saves you time, drop a star! ⭐