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
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.
-
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).
Feature | Description |
---|---|
🔄 Bidirectional conversion |
cuws detects the source format or let you force it. |
📂 Directory mode | Convert whole trees while mirroring structure (requires output directory specified). |
🏗️ TypeScript API | Import convertString() , convertFile() , or convertDirectory() in your scripts. |
🪝 Streaming first | Works perfectly in Unix pipes & GitHub Actions. |
🐚 Single‑file binary | ES module with hashbang—no compilation required. |
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
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).
cuws [options]
Flag | Default | Description |
---|---|---|
-i, --input <path> |
- |
Path to source file or - for stdin. Conflicts with -d . |
-o, --output <path> |
- |
Path to dest file (with -i ) or output directory (required with -d ). |
-r, --reverse |
false |
Convert from Windsurf (.md) to Cursor (.mdc). |
--force <format> |
Override auto-detection (cursor or windsurf ). |
|
-d, --dir <path> |
Recursively convert directory. Requires -o for output. Conflicts with -i . |
|
--dry-run |
false |
Print planned actions, don’t write files. |
--verbose |
false |
Extra logging. |
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.
-
Clone & install deps:
git clone https://github.com/YOUR_ORG/cursor-windsurf-convert.git cd cursor-windsurf-convert && pnpm install
-
Link the CLI for local testing:
pnpm run build # if you transpile pnpm link --global # exposes `cuws` in PATH
-
Run tests:
pnpm test
The CLI file must start with #!/usr/bin/env node
and be chmod +x
.
PRs welcome! Check the open issues or open a new one. Also see CONTRIBUTING.md for details.
- [x] One‑file conversion
- [x] Directory batch mode
Q | A |
---|---|
Does it change my markdown body? | Nope. Only the YAML/MD header is mapped. |
Can I embed this in my own tool? | Absolutely—import the TS API. |
What if I get YAML errors? |
cuws uses a strict YAML parser. See YAML Parsing Strictness below. |
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
- Incorrect:
-
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 ifdescription
is not needed.
- Incorrect:
- 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 betitle: 'My Rule: A Detailed Look'
ortitle: "My Rule: A Detailed Look"
. -
cuws
attempts to auto-quote problematicglobs
values during parsing, but other fields might require manual quoting if they contain special characters that could be misinterpreted by the YAML parser.
- Example:
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.
MIT © 2025 Gordon Mickel
⭐ If this saves you time, drop a star! ⭐